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I think this one will be for Megan as well, having discovered that 
Windows was useful after all, in that it has a Games group. 
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Preface 


Of all the pictures hanging on the walls of the loft where I work, none 
is more evocative of everything removed from computers than 
Maxfield Parrish’s Daybreak. Depicting a timeless place utterly devoid 
of telephones, monitors, and mice, it speaks of a world where the 
phrase “state of the art” would probably refer to how close the 
painting was to completion. There are several Parrish reproductions 
up here. Daybreak appears in Fig. P-1, if only in black and white. 

One of the unfortunate things about the layout of the place at the 
moment is that the big Pentium with buckets of memory to run 
Windows 95 is located such that, in sitting at its monitor, one faces 
away from most of the good pictures. After considering this for a time, 
I began to wonder if having something like Daybreak as Windows 
wallpaper might in some way undermine the austere cubist cyberspace 
of the Windows desktop. The results can be seen in Fig. P-2. 

In a sense this worked. It strongly motivated me to leave all of 
Windows minimized for as much of the time as possible. The picture 
was actually quite luminous and attractive displayed on a monitor—as 
long as there were no windows getting in its way. 
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I don’t use Daybreak as wallpaper any longer. Aside from turning the 
Pentium machine into an almost wholly unproductive museum piece, 
in reflection it seemed out of keeping with the artist. In time, I hung a 
copy of John Waterhouse’s Hylas and the Nymphs beside the 
computer, which managed to improve the apprehension of the place 
without inflicting anything untoward on either Windows or anyone’s 
favorite artist. Out of deference to the publisher, Hylas and the 
Nymphs will not be appearing in this book, but you might want to 
track it down if your Windows system needs a bit of enlivening as well. 
A small version of it can be found at the web page 
http://www.mindworkshop.com in the section entitled Indecent 
Images. 

The graphical nature of Windows and Windows applications makes 
the prospect of actually including something other than the line 
graphics of Windows itself in your software a lot more realistic than 
would be the case for DOS software. Aside from merely pouring great 
art into your Windows desktop, you can actually use complex 
bitmapped graphics in the software you write. Having pictures rather 
than merely icons and arrows in your applications can do a lot to 
make them both more understandable and more user-friendly in the 
less conventional sense of being genuinely human, rather than a 
machine attempting to play at being less machine-like. Your software 
might not call for having a Maxfield Parrish painting in its About 
box—or then again, it might—but you’ll find that being able to use 
graphics that don’t look like the typical Windows boxes and buttons 
will provide you with a whole new way to drive your applications. 

In a more conventional sense, being able to work with commercial 
bitmapped graphics will allow you to write Windows applications that 
can exchange graphics with other software. Aside from dealing with 
the import and export paths inherent in Windows—facilities that are 
well documented and pretty easy to use—the available bitmapped 
graphics formats will let you work with pictures that have originated in 
other environments, such as DOS and the Macintosh, and to create 
graphics for export to these alternate platforms. 

The difficulty in working with bitmapped graphics is that most of the 
popular commercial graphic file formats—PCX, TIFF, GIF, and so 
on—are not all that well documented and that documentation that 





does exist is fairly tricky to come by. None of it really pertains to 
Windows. 

While, in theory, this latter issue shouldn’t matter—most file format 
specifications that provide example source code at all do so in the C 
language, the preferred choice for Windows applications as well—in 
practice, having to translate between the universe of DOS and that of 
Windows is often exceedingly involved. Having to do so while you’re 
also trying to make sense of the bizarre notation of graphic file 
formats, documents that are very often written in Sanskrit and 
subsequently translated with a random text generator, can make the 
task of integrating bitmapped graphics into your Windows applications 
supremely daunting. 

This book speaks to the problems of using popular bitmapped 
graphics file formats in Windows software. It will provide you with 
complete descriptions and source code for several of the most 
commonly encountered bitmapped graphics formats. Perhaps more to 
the point, it also includes compiled DLLs ready to import into your 
applications. You need never understand anything about graphic files 
beyond how to call the DLL functions if you don’t want to. 

The Graphic Workshop 
connection 

As you might fully appreciate when you’ve had a chance to read 
further in this book, commercial bitmapped graphic file formats are 
not quite as well documented as they can first appear. There are 
variations on them: applications that create slightly illegal files, other 
applications that don’t read imported files quite as they should, and so 
on. While it would be convenient to deal with these situations by 
ignoring them, frequent error message dialogs will do nothing to 
improve the satisfaction of the users of your Windows applications. 

The source code in this book didn’t start here. It has been derived 
from a large graphics package called Graphic Workshop for Windows, 
the executable version of which can be found on the companion 
CD-ROM for this book. Graphic Workshop is among the most widely 





used image file viewing and manipulation packages. Its original DOS 
implementation has been around for about a decade. It—and hence 
the source code in this book—have had the opportunity to sample just 
about all the awkward, funky, and slightly warped image files in the 
known universe. Not only will this book give you source that is easy to 
understand and to implement in your software, it will also provide you 
with functions that have been crafted to deal with real-world graphics. 

I hope that you enjoy Bitmapped Graphics for Windows and OS/2. 
Whether you’re new to Windows and Warp programming—and would 
like to work with example programs that are genuinely interesting—or 
if you’re writing commercial applications and need a leg up on getting 
bitmapped graphics into your code, this book should help you avoid a 
lot of the grunt work. 

It will hand you the whole works on a plate, and that’s a real plate, 
rather than those virtual reality plates that come spinning at you from 
the corner of your monitor flickering with promise but ultimately 
proving to hold nothing but pixels. 

Steve Rimmer 

CIS: 70451,2734 

BBS: (905) 936-9503 

e-mail: alchemy @accesspt. north. net 

web: http://www.mindworkshop.com 
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STENSIBLY user-friendly operating systems such as Windows 
and OS/2 Warp present themselves as being very graphical, 
and they seem as if they should be crawling with graphical facilities 
behind all those windows and dialogs. Sadly, they’re not—most of the 
really interesting things that you can do with graphics under Windows 
or Warp entail that you write almost everything involved from scratch. 
The hundreds of API calls available to Windows and Warp 
programmers will avail you not. 

One of the areas of graphic programming that is most likely to cause 
you to damage an otherwise pristine wall by banging your head 
against it is that of reading and writing graphics that have been stored 
in commercial graphic formats, such as GIF, PCX, JPEG, and so on. 
You probably already have a sense of the level of complexity posed by 
this weighty issue, having sprung for this book. 

Ancillary to this issue is how to deal with large bitmapped objects in 
an environment that is willing to permit you to do so only with the 
application of a considerable degree of stealth. While Windows and 
Warp are happy to present a graphical face to their users, they’re 
much less forthcoming about permitting software running under them 
to do the same. Big pictures scare the creators of these sorts of 
environments right out of their corporate-lease beamers. 

In fact, there are a number of finer points involved in writing Windows 
and Warp software that can work realistically with large graphics. Not 
all of them have a lot to do with graphics, and one or two involve that 
other prominent element in software development, to wit, lawyers. 
This book will get into each of them in time. You might ultimately find 
yourself choosing a bare spot on your wall nonetheless. 

The fundamental issue to be dealt with in this book is that of storing a 
bitmapped image in a disk file and reading it back, such that it can be 
displayed or otherwise manipulated. This seems as if it should be a 
problem so simple as to require a pamphlet at best—a book about this 
topic should represent unspeakable overkill. In a perfect world, this 
would probably be so, but in a perfect world the phrase “Microsoft 
technical support” would not be immediately followed by “Please hold, 
your call is very important to us.” 
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To fully understand why storing pictures on a disk is so mind- 
numbingly complex, you’ll have to better appreciate what a bitmap is, 
why small is never small enough in dealing with one, and how many 
angels can dance on the head of a pin without one of them falling off 
and suing the rest for damages. That last point is fundamental, by the 
way—being taken to court by a mythical entity having no physical 
form is a bitch. 

Depending on how you look at it, this book will provide you with a 
workable grasp of most of the foregoing issues—Microsoft’s technical 
support and the dancing angels will remain your problem—or it will 
provide you with a convenient way to ignore the whole works. Over 
the next few chapters, you’ll encounter the source code for libraries to 
do all sorts of useful things with bitmapped graphics. You’ll be able to 
see how these functions work and, as such, achieve a higher 
awareness of commercial graphic file formats and the internal 
bitmapped graphic functions of Windows and Warp, such as they are. 

Alternately, you’ll be able to copy the compiled versions of these 
libraries from the CD-ROM that accompanies this book, link them to 
your application and never have to understand what any of them are 
doing. This arguably isn’t very Zen-like, but it will get you back to the 
real task of designing your software in minutes, instead of weeks. 

This book includes functions to read and write graphics in the 
following formats: 

CompuServe GIF 

PC Paintbrush PCX 

TIFF 

JPEG 

Windows and OS/2 BMP 
PNG 

Truevision Targa 





You’ll also find functions in this book to manipulate bitmaps once 
they’ve been read from a graphic file. This includes things like: 

Displaying them 

Dithering them so that they display correctly 
Printing them 

Moving them on and off the clipboard 

Maintaining them in memory 

Obtaining and displaying information about them 

It’s likely that not all of the foregoing will make complete sense just 
now, and some of it might actually seem a bit deceptive. It will become 
clearer with time and multiple passes through a C compiler. 

Bitmaps: what Pooh shot 

Your eye is the single most sophisticated image digitizing mechanism 
in the known universe—at least, it is unless you bought one of those 
cheap monitors from Sears and habitually sit too close to it. One of 
the remarkable things about your eye is a level of user-friendliness that 
would make the user-friendliness of even the most over-hyped software 
look like naked aggression by comparison. It’s so easy to operate, it 
doesn’t even come with instructions. 

The visual world is analog, which is to say that real-world images are 
not comprised of discrete bits of information unless you want to get 
down to the level of quantum mechanics. Every image is comprised of 
an infinite number of details. This makes for a really interesting visual 
world, but it’s a problem for sensory mechanisms that want to perceive 
it. Infinity is uncomfortably large. All sensory mechanisms want to deal 
with a finite number of discrete objects—they are required to split the 
images that they perceive into little bits of light. 

Your eye does this by using a blanket of photosensitive cells—those of 
us who didn’t cut high school biology will recall these as being called 
rods and cones. They split up the analog world into a lot of little bits 
of information, which your brain can subsequently make sense of. 
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While your brain is sophisticated enough to filter all this into a 
perception of an analog world, what it really sees through your eyes is 
a matrix of very small colored dots. 

A computer that wanted to represent visual reality would be 
confronted with precisely the same problem as that of your eye, and 
its designers would solve it in much the same way. Rather than saying 
“let there be light” or “give it twenty-million years and let’s see what 
evolves,” computer designers simply copied the way eyes work into a 
digital equivalent. They created bitmaps. 

A bitmap is a matrix of colored dots. Computer-based bitmaps are a 
lot coarser than the bitmaps produced by your eyes, of course, 
because they’re being handled by a computer billions of times less 
powerful than the one your eyes are connected to. Mind you, the one 
your eyes are connected to isn’t likely to be recalled because of a 
floating-point divide bug—extensive beta testing has its advantages. 

Figure 1-1 illustrates the nature of a bitmap. The left side of the 
picture appears to be an analog image; that is, what your eye might 
see were it to be pointed at the image in question. The right side 
illustrates how the image is really constructed. The colored dots that 
make it up are too small to see when you view the image in its 
entirety, but they’re present nonetheless. 



Figure 1 -1 



A real-world image (a) and a detail illustrating how real the real world 
really is (b). 







Most technologies that display images can be seen to be bitmaps if you 
look carefully. Your monitor is one, as is a television set. Photography 
is also a bitmapped technology—its matrix of dots is actually a matrix 
of silver salt crystals, so the dots are exceedingly fine. Computer-based 
imaging can’t approach the resolution of either chemical photography 
or of the biological camera in your head, but because we have fairly 
tolerant brains, it rarely has to try. 

The colored dots that make up a bitmap are properly called pixels — 
unless you work for IBM, in which case they’re called pels. If you’re 
uncertain whether you should be referring to them as pixels or pels, 
buy a small potted plant and leave it on your desk for a few days. If 
the plant is confiscated by your boss, refer to them as pels. 

In addition to providing your eyes with infinitely small details, the 
analog world presents it with images having the potential for an 
infinite number of possible colors. Again keeping in mind that ideas 
like “infinite” really upset computer designers, digital bitmaps can 
represent a large but finite number of colors. For reasons we’ll get to 
in a moment, the bitmaps to be discussed in this book will be able to 
deal with a maximum of 16,777,216 possible colors. It’s this rather 
large number, and a bit of calculator action, that will begin to explain 
why commercial bitmapped graphic files are so uncomfortably large. 

Color is represented on a computer by using varying amounts of red, 
green, and blue light. These are the primary colors of what’s called 
additive color —by adding percentages of red, green, and blue to the 
initial blackness of your monitor, any color can be created. 

In the simplest sort of bitmapped image, each pixel is represented by 
three numbers to store the amounts of red, green, and blue light that 
define the color of the pixel in question. The smallest useful object for 
storing numbers on a computer is a byte—in this sort of bitmap, each 
pixel requires one byte for each color index for a total of three bytes 
per pixel. As a byte represents eight bits, each pixel requires 24 bits to 
store all its color information. This defines the maximum number of 
discrete colors this sort of bitmap can represent as 2 24 , or 
16,777,216. 
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Here’s where you can use the aforementioned calculator. The lowest 
resolution for a monitor displaying a Windows or Warp desktop is 640 
by 480 pixels. In a bitmap of this resolution, then, there would be 
three bytes per pixel, for a total of 640 x 480 x 3 bytes, or 900 
kilobytes. This is the resolution of the bitmap that defines the left side 
of Fig. 1-1. The raw graphic file for that figure would have required 
more storage space than the text for this entire book. 

This is the fundamental issue out of which arises all the complexities 
that will be addressed in this book. Bitmapped graphics are huge 
entities, and they become huger still as they get better looking. There 
are ways to reduce the level of hugeness represented by bitmaps, but 
they involve all sorts of stealth and treachery. The graphic file formats 
I listed a while back are the repositories of said stealth and treachery. 

There are two ways to store a bitmap in a space smaller than it would 
naturally occupy: You can reduce the amount of space required to 
store one pixel, and you can algorithmically compress the image data. 
We’ll deal with the latter issue first. 

You probably use data compression all the time—it’s the basis of 
archiving packages such as PKZIP and of the hardware data 
compression used by modems. While contemporary data compression 
uses very sophisticated algorithms to squeeze data into the smallest 
possible files, the basis of data compression can be seen in what’s 
called run-length compression. 

Figure 1-2 illustrates a simple bitmapped graphic. In this example, the 
bitmap uses only black and white pixels—compression can be applied 
to color images as well. 

One of the things you’ll no doubt observe about Fig. 1-2 is that it 
embodies a lot of white space. The first horizontal row of pixels is 
entirely white. If this bitmap had the structure we’ve been discussing 
and the dimensions 640 by 480, the first row of the bitmap would 
occupy 1920 bytes. 

If you wanted to store this line in fewer than 1920 bytes, you could 
replace it with a token; that is, a code that said “replace me with 640 
white pixels.” Assuming that the code required fewer than 1920 pixels 










Figure 1 -2 




A simple bitmapped graphic, all ready to be compressed. 


to store—a likely assumption—this would reduce the amount of space 
required to store this line. Applied to the entire bitmap, this type of 
encoding would reduce the amount of space the bitmap would require 
to store. 

Software confronted with unpacking the bitmap would know how to 
spot the compression codes and expand them back to the original data 
they represented. As such, compression wouldn’t actually change the 
contents of a bitmap—it would just make it more manageable when it’s 
stored. 

While illustrative of how image compression works, this type of simple 
run-length compression doesn’t actually handle complex photorealistic 
data very well. In fact, a really complex image handled this way can 
actually result in a file that’s larger than the uncompressed image 
would have been. Run-length compression works by locating “runs” of 
consecutive identical pixels and encoding them. If none of the 








consecutive pixels in an image are identical, there’s nothing to 
compress. In a real world run-length encoding method, however, 
codes would still have to be inserted in the compressed data to tell the 
unpacking software that the compression hasn’t done anything. 

We’ll deal with the details of more sophisticated compression 
algorithms later in this book—you might find that you want to skip 
over them when you encounter these bits. Data compression is one of 
those subjects that will put to sleep people who find long-polymer 
molecule inorganic chemistry interesting. 

The sorts of bitmaps we’ve been discussing thus far have 24 bits of 
color per pixel, and perhaps not surprisingly, are referred to as 
supporting “24-bit color.” They’re also called true color bitmaps. 

They represent the high end of bitmap color. Because each pixel in a 
true color bitmap can be subtly different from its neighbor, true color 
bitmaps also represent the worst case for compression—even the 
application of really sophisticated compression algorithms rarely 
makes much of a dent in a true color bitmap of a photorealistic 
subject. There’s a way to cheat around this problem, to be discussed 
later in this book when we get to JPEG files, but for the sake of this 
discussion, let’s allow that 24-bit color can’t be readily compressed. 

You can improve on this situation—and the size of bitmaps in 
general—hy using fewer bytes to store each pixel. For example, you 
can use five bits to represent each of the three color indices of a pixel, 
rather than eight, for a total of 15 bits rather than 24. This will allow 
each pixel to fit into two bytes, albeit with one of the color values split 
between them. A 24-bit bitmap reduced to a 15-bit bitmap would get 
a third smaller. It would also have only 2 15 bits of color, or 32,768 
possible colors, down from 16,777,216. This would make it more 
likely that adjacent pixels would be of the same color, and as such 
make such a bitmap more readily compressed. This sort of bitmap is 
referred to as high color. 

High color bitmaps will only turn up once in this book—despite the 
apparent space saving offered by high color, it’s not readily used. It’s 
somewhat processor-intensive to work with, and perhaps the authors 
of the bitmapped graphic formats to be discussed in the following 
chapters figured that inasmuch as a 600-kilobyte bitmap and a 900- 





kilobyte bitmap are both radically huge, one might as well eat the 
extra 300 kilobytes and have exemplary color. 

For practical purposes, the next step down from true color is palette 
color. Palette color bitmaps work a bit differently from the sorts of 
bitmaps we’ve been dealing with thus far. The simplest sort of palette 
color is found in an eight-bit bitmap, wherein each pixel is represented 
by one byte. 

Eight bits isn’t anything like enough to represent the color indices of a 
pixel in the way the three bytes of a true color bitmap does. A palette- 
color bitmap consists of a list of 256 true colors—the palette for the 
image—that defines all the colors available for use in the image. Each 
pixel in the image is actually an index into this table. Rather than 
defining the color directly, the bytes that make up the pixels of a 
palette-color image store the numbers of colors in the color table, 
which in turn defines the colors. 

Eight-bit palette color reduces the amount of memory required to store 
a bitmap to one-third of what would be required to store the same 
image as a true color bitmap. The catch is that, if you reduce a true 
color photorealistic image to 256 colors without a pretty high degree 
of stealth, it won’t look photorealistic any more. Figure 1-3 illustrates 
this. 

It’s fairly easy to understand what’s happened in Fig. 1-3. The source 
image was initially analyzed to come up with a list of 256 colors that 
best represented the original colors. Each pixel in the source image 
was then replaced by the closest color in the color palette. This clearly 
doesn’t work—it destroys buckets of detail in the source image 
because it replaces a lot of pixels that started off being different colors 
with pixels that are the same color, having too few colors to reflect all 
the subtle color variations in the original image. 

Figure 1-4 also illustrates an image reduced to 256 colors. 

The right side of Fig. 1-4 looks a lot better than the right side of Fig. 
1-3 because Fig. 1-4 knew about dithering. Dithering is what 
computers do to make you think they have more colors on hand than 
they really do. Here’s a simple example. Suppose you wanted to paint 
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a wall green, but you only had blue and yellow paint. You, being an 
analog creature at heart, would upend both cans of paint into a 
bucket, stir its contents vigorously and pat yourself on the back for 
having created green paint where once there was none. 

A computer confronted with the same problem, that of painting an 
area of your screen green when it only had yellow and blue pixels to 
work with, would handle the matter differently. It would paint each 
odd numbered pixel yellow and each even numbered pixel blue. From 
a few inches away, the result would look like a pretty convincing 
simulation of green. 

The process of dithering can be applied to the somewhat more 
complex issue of reducing the number of colors in an image. A 
dithered image, like the one in Fig. 1-4, uses alternating pixels of 
colors that the image does have to simulate the colors that it doesn’t 
have. In reality, this trades image color depth for image resolution, but 
the effect of dithering is usually pretty convincing. It allows 
photorealistic images to be represented in 256 colors. 

In fact, dithered palette-color images are suitable for applications in 
which modest resolution display images are called for—they’re 
undesirable for high-end imaging, especially if you have designs on 
inflicting some image processing on the pictures in question. The 
alternating pixels created by a dithering algorithm impose all sorts of 
limitations on what can be done to the resulting graphics. 

The alternating pixels of a dithered image also serve to fox a 
compression algorithm almost as well as the subtly different pixels of a 
true color bitmap. In practice, palette color images do compress to a 
degree, but reducing an image from 24 to 8 bits of color might not 
avail you of the really small files you’d expect with this loss of color 
depth. 

Palette color images can represent fewer than 256 colors. The usual 
next step down is to 16 colors, in which case each pixel represents 
four bits. One byte can store two pixels in this case. Sixteen colors 
can’t really represent photorealistic images in a way to make you think 
they’re anything other than computer art, but 16-color images are 





useful for line drawing and mechanical objects such as a Windows or 
Warp desktop. 

The simplest form of bitmaps are those with only two colors. By 
default the two colors involved are assumed to be black and white. In 
this case, one byte can hold eight pixels, with each bit of the byte in 
question representing the state of a pixel. 

It’s important to note that the expression “black and white” means 
different things to a human being and to a computer. A black-and- 
white photograph—in humanspeak—is what a computer would call a 
“gray scale” image. This is a color image in which all the colors are 
gray. A black-and-white picture to a computer is a two-color bitmap. 

Device-independent bitmaps 

To be useful, the bitmapped image that’s unpacked from a commercial 
graphic file format—such as PNG, GIF, or JPEG—must be stored in 
memory in a form that tells software wanting to access it enough 
about it to use it correctly. Specifically, a function that wanted to 
display, print, or perhaps recompress a bitmap into another format 
would want to know things like: 

The dimensions in pixels of the bitmap. 

The color depth of the bitmap; that is, the maximum number of 
colors it can support. 

The color palette of the bitmap, if it has one. 

Where the actual image data resides. 

Windows defines a structure to maintain this information, and as it’s 
actually required for some of the Windows API calls to be used by the 
software in this book, it’s convenient to maintain all internal bitmaps 
this way. The structure is what Windows calls a device-independent 
bitmap. 
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I’m not ignoring OS/2 in this discussion, by the way—Warp 
programmers can use a similar sort of device-independent bitmap in 
their software, to be dealt with in a moment. 

A device-independent bitmap consists of a header, an optional array of 
palette colors, then the actual bitmap data that defines the image in 
question. Here’s what the header looks like: 

typedef struct { 

DWORD biSize; 

LONG biWidth; 

LONG biHeight; 

WORD biPlanes; 

WORD biBitCount; 

DWORD biCompression; 

DWORD biSizelmage; 

LONG biXPelsPerMeter; 

LONG biYPelsPerMeter; 

DWORD biClrUsed; 

DWORD biClrlmportant; 

} BITMAPINFOHEADER; 

typedef BITMAPINFOHEADER FAR* LPBITMAPINFOHEADER; 

The BITMAPINFOHEADER is extremely useful in creating the sort of 
software this book will deal with, and it will turn up frequently from 
now on. Here’s what its fields do: 

biSize —This is the size of the header. It should be set to 
sizeof(BITMAPINFOHEADER). For reasons that will turn up in the 
chapter of this book that discusses BMP files, other values can appear 
in this field in some cases. 

biWidth —This is the width of the bitmap in pixels. 
biHeight —This is the height of the bitmap in pixels. 
biPlanes —This is always set to one. 

biBitCount—This is the number of bits of color supported by the 
bitmap. Device-independent bitmaps can support 1, 4, 8, and 24 bits 
of color. Intermediate color depths must be promoted to the next 
highest value. 






biCompression —This defines whether the bitmap is compressed. In 
the context of this book, device-independent bitmaps are never 
compressed, and this field should be set to zero. More will be said 
about the compression supported by device-independent bitmaps in 
the chapter that deals with BMP files. 

biSizelmage —This is the size of the bitmap for this image in bytes. 

biXPelsPerMeter —This is the horizontal resolution of the image in 
pixels per meter. Set it to zero, and ignore it. 

biYPelsPerMeter —This is the vertical resolution of the image, also in 
pixels per meter. Ignore this one, too. 

biCIrUsed —This is the number of colors in the color palette of the 
image. It will be 0 for 24-bit images or 1 << biBitCount for palette 
color images. Windows says this can be set to zero, but for the 
purposes of this book, it should always be filled in. 

biCIrlmportant —This is the number of colors in the color palette that 
are important. Opinions differ as to what constitutes an important 
color—I like British racing green, myself. Set this to zero or the same 
value as appears in biCIrUsed. 

Unless your bitmap contains a 24-bit image, the next thing after a 
BITMAPINFOHEADER will be an array of biCIrUsed RGBQUAD 
objects. An RGBQUAD looks like this: 

typedef struct { 

BYTE rgbBlue; 

BYTE rgbGreen; 

BYTE rgbRed; 

BYTE rgbReserved; 

} RGBQUAD; 

typedef RGBQUAD FAR* LPRGBQUAD; 

The first three fields of an RGBQUAD define the red, green, and blue 
indices of the color the palette entry in question represents. The 
rgbReserved entry should be set to zero. It’s actually used as a flag 
register in some cases when Windows is meddling with device¬ 
independent bitmaps, but for the most part, it just serves to pad the 







size of a palette entry out to four bytes, as hard-coded multiplication 
by four is quicker than multiplication by three. 

Note that the blue index comes first. This is the opposite of how RGB 
colors are stored in many other environments. 

It’s important to note that there will never be any RGBQUAD objects 
in a 24-bit bitmap. As we’ll get to in a moment, there’s a fairly 
common error surrounding this, too. It involves integer sizes. 

The bitmap information in a device-independent bitmap is stored 
upside down, such that the bottom line of the image as it’s to be 
displayed is the first line in the buffer. If you don’t keep this in mind 
when you’re writing software to work with device-independent 
bitmaps, they’ll often show up inverted. 

The lines of bitmap information in a device-independent bitmap are 
always padded out to end on an even word boundary, as most 
processors can work faster if they’re permitted to assume that objects 
are always word-aligned. You can calculate the correct number of bytes 
for a line of pixels in a device-independent bitmap by using the 
following macro: 

#define WIDTHBYTES(n) ((n+31)/32*4) 

The argument passed to WIDTHBYTES should be the number of pixels 
in the horizontal dimension of the bitmap in question multiplied by the 
color depth in bits; that is, biWidth*biBitCount. Keep in mind that this 
calculation assumes that the numbers are integers rather than floating¬ 
point values. It rounds the result up to the nearest 16 and then divides 
it by 8—the number of bits in a byte. 

Because device-independent bitmaps are so commonly used in writing 
Windows graphic software, it’s convenient to create a set of macros to 
access the fields of a BITMAPINFOHEADER. While they don’t do 
anything particularly magical, they will relieve you of the need to 
remember all those field names. They’ll also make porting code that 
works with device-independent bitmaps between Windows and OS/2 
fairly painless, as a corresponding set of macros can be defined for 
Warp. Here they are: 



#define LPBimage(Ipbi) \ 

((HPSTR)lpbi+lpbi->biSize+\ 

(long)(lpbi->biClrUsed*sizeof(RGBQUAD))) 

#define LPBwidth(Ipbi) ((unsigned int)lpbi->biWidth) 

#define LPBdepth(Ipbi) ((unsigned int)lpbi->biHeight) 

#define LPBbits(Ipbi) ((unsigned int)lpbi->biBitCount) 

#define LPBlinewidth(Ipbi) \ 

(WIDTHBYTES((WORD)lpbi->biWidth*lpbi->biBitCount)) 

#define LPBcolors(Ipbi) ((unsigned int)lpbi->biClrUsed) 

#define LPBcolormap(Ipbi) \ 

(LPRGBQUAD)((LPSTR)lpbi+lpbi->biSize) 

The LPBwidth and LPBdepth macros access the pixel dimensions of a 
device-independent bitmap. The LPBbits macro accesses the color 
depth in bits. The LPBlinewidth macro calculates the number of bytes 
in one line of image data. The LPBcolors macro returns the number 
of colors in the color palette of the bitmap in question—note that it 
relies on the biCIrUsed field being set correctly, and not defaulting to 
zero. The LPBimage macro returns a pointer to the beginning of the 
image data of a device-independent bitmap, and the LPBcolormap 
macro returns a pointer to the beginning of the color map of a 
bitmap. All these macros expect to be passed a pointer to a device¬ 
independent bitmap as their argument; that is, an 
LPBITMAPINFOHEADER object. 

Some of the casts in these macros might look a bit peculiar if you 
haven’t gotten down and dirty with Windows’ memory models and 
such before. I’ll deal with them in greater detail shortly. 

It’s worth noting that Windows defines a second device-independent 
bitmap header structure that is easily confused with the one that’s 
been discussed thus far. Watch out for BITMAPINFO, rather than 
BITMAPINFOHEADER. Here’s how it’s defined: 

typedef struct { 

BITMAPINFOHEADER bmiHeader; 

RGBQUAD bmiColors[1]; 

} BITMAPINFO; 

A BITMAPINFO object is a BITMAPINFOHEADER object with an 
array of one RGBQUAD palette entry tacked onto it. This makes it 
easier to access the palette entries. In most cases, the two objects can 
be considered interchangeable—at least, they can in the context of 
this book. A BITMAPINFOHEADER will always appear as part of a 





complete device-independent bitmap. Note that some Windows 
functions expect one or the other of these objects—some casting 
between them is necessary from time to time. 

Because a complete device-independent bitmap is a fairly large and 
complex object, it’s handy to have a function create these things. 
Figure 1-5 shows what it looks like. 

The CreateDIB function will allocate a buffer large enough to store a 
bitmap of the dimensions and color depth specified in its arguments. 
The palette argument defines a pointer to a conventional list of 
palette colors. These are stored as three-byte entries in the order red, 
green, and blue. 

It’s probably worth digressing for a moment about palette entries 
and RGB color storage under Windows. Like much of the internal 
API structures of Windows, color definitions are handled peculiarly 
for no obvious reason. In most environments, RGB colors are stored 
in the order red, green, and blue. Under Windows, they’re stored in 
the order blue, green, and red; that is, with the red and blue indices 
interchanged. It’s useful to define some constants to specify where 
to find the colors in a color value or palette entry. The following are 
the offsets for a normal color entry: 

ttdefine RGB_RED 0 
#define RGB_GREEN 1 
#define RGB_BLUE 2 

This is the size of a normal color entry, as would be found in a list of 
palette colors somewhere other than in a device-independent bitmap: 

#define RGB_SIZE 3 

The following define the color offsets as Windows uses them: 

#define WRGB_RED 2 
#define WRGB_GREEN 1 
#define WRGB_BLUE 0 

As long as you’re dealing exclusively with device-independent bitmaps, 
the latter set of constants will always be correct. Most of the 
commercial graphic file formats to be discussed in this book use the 
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HANDLE CreateDib(WORD dx,WORD dy,LPSTR palette,WORD bits) 

{ 

HANDLE hdibN; 

BITMAPINFOHEADER bi; 

LPBITMAPINFOHEADER lpbi; 

RGBQUAD FAR *pRgb; 

WORD i; 

bits=AdjustDIBits(bits); 

bi.biSize = (DWORD)sizeof(BITMAPINFOHEADER); 

bi.biplanes = 1; 

bi.biBitCount = bits; 

bi.biWidth = (DWORD)dx; 

bi.biHeight = (DWORD) dy; 

bi.biCompression = BI_RGB; 

bi.biXPelsPerMeter = 0; 

bi.biYPelsPerMeter = 0; 

bi.biClrUsed = bits > 8 ? 0L : (DWORD) ((l«bits) & Oxffff) ; 
bi.biClrlmportant = bi.biClrUsed; 

bi.biSizeImage=WIDTHBYTES(bi.biWidth*bi.biBitCount)*(long)dy; 

if((hdibN=GlobalAlloc(GMEM_MOVEABLE | 

GMEM_DISCARDABLE | GMEM_ZEROINIT, 
sizeof(BITMAPINFOHEADER) + 

+(long)bi.biClrUsed* 

sizeof(RGBQUAD)+bi.biSizelmage))==NULL) 
return(NULL); 

if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(hdibN)) ==NULL) { 
GlobalFree(hdibN); 
return(NULL); 

} 

lmemcpy((LPSTR)lpbi,(LPSTR)&bi,sizeof(BITMAPINFOHEADER)); 

if(palette != NULL) { 

pRgb = (RGBQUAD FAR *)((LPSTR)lpbi+ 

(unsigned int)lpbi->biSize); 
for(i=0;i<bi.biClrUsed;++i) { 

pRgb[i].rgbRed=(char)palette[i*RGB_SIZE+RGB_RED]; 
pRgb[i].rgbGreen=(char)palette[i*RGB_SIZE+RGB_GREEN]; 
pRgb[i].rgbBlue=(char)palette[i*RGB_SIZE+RGB_BLUE]; 
pRgb[i].rgbReserved=0; 

} 

} 

GlobalUnlock(hdibN); 
return(hdibN); 


Figure 1 -5 



A function that creates complete device-independent bitmaps. 




more conventional red, green, and blue order and, as such, the first 
set of constants. 

The CreateDIB function expects its palette argument to point to a list 
of three-byte color entries stored in red, green, and blue order—you’ll 
note that it uses the first set of constants internally. 

You should also keep in mind that the byte order for RGB values in 
lines of 24-bit images can also vary. Once again, the real world uses 
the order red, green, and blue and Windows uses the order blue, green 
and red. Some line swabbing is called for on occasion. 

And now, a digression about 
Windows" memory management 

You’d probably expect the CreateDIB function to return an 
LPBITMAPINFOHEADER object; that is, a pointer to a device¬ 
independent bitmap. It could do this, although in the complex 
environment of Windows software that handled something as large as 
a bitmap as an object referenced by a pointer would not be well 
received. Understanding how all this works is essential to working with 
objects in memory under Windows. 

Under DOS—a very much simpler environment than Windows— 
memory is always allocated using pointers. This means, for example, 
that you could allocate a block of 1000 bytes of memory like this: 

char *p; 
p=malloc(1000) ; 

This works, and in fact you could do the same thing under Windows. 
You shouldn’t, however. 

Consider this example of memory allocation: 

char *p[3]; 
p[0]=malloc(1000); 
p[1]=malloc (1000) ; 
p[2]=malloc(1000); 
free(p[1]); 
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When all this is over, you’d probably think that there’s a total of 2000 
bytes of memory allocated, and as such removed from the pool of free 
memory available for allocation by subsequent calls to malloc. This is 
somewhat true, but note that the block of memory formerly pointed to 
by p[ 1 ] is trapped between two other blocks. Unless a subsequent call 
to malloc is looking for a block 1000 bytes long or smaller, this bit of 
memory, while unallocated, is effectively useless. 

This is the fundamental limitation of fixed memory allocation; that is, 
of allocating memory objects and referencing them through a pointer. 
The memory manager responsible for handing out blocks of memory 
can’t perform what’s informally known as “garbage collection”; that 
is, it can’t combine trapped blocks of formerly allocated memory and 
fuse them into one larger block. To do this, it would have to be able to 
move the currently allocated blocks in memory. Because the pointers 
pointing to them wouldn’t know that they’d moved, said pointers 
would find themselves pointing to the wrong places after the garbage 
had been collected. 

This would be exceedingly messy. 

Because DOS is a single-task operating system and kind of old and 
funky, pointer-based memory is good enough for the sorts of things 
DOS applications are usually called upon to do. Perhaps more to the 
point, Microsoft has made most of the money it’s likely to make from 
DOS and wasn’t about to write a whole new memory-management 
package for it this late in its life. 

Windows gets around this problem by returning memory handles, 
rather than memory pointers, from its central memory allocation 
function, GlobalAlloc. A handle isn’t a pointer to memory—it’s more 
like a claim check. It’s a magic number through which you can refer to 
a previously allocated block of memory. A memory handle tells 
Windows which block of memory you’re interested in dealing with, but 
only Windows knows where it is. Furthermore, its location can change 
as Windows performs its internal garbage collection. In fact, if 
Windows finds itself with a shortage of memory and it decides that 
your block of memory probably won’t be needed for a while, it might 
spill the contents of the block out to your hard drive and free its 









memory entirely. None of this need affect your application’s use of its 
memory, however, because you’ll never know what Windows is up to. 

To access a block of memory referenced by a memory handle, you 
must pass the handle to the GlobaJLock function. Allowing that all 
goes well, GlobalLock will tell Windows that it is no longer 
empowered to move your block of memory around. If it had previously 
been spilled to disk, GlobalLock will force Windows to load its 
contents back into memory. The GlobalLock function will return a 
conventional pointer to your memory, which you can treat just as you 
would a pointer returned under DOS by malloc. 

You should only leave memory handles locked for as long as you 
require the memory they represent to be directly accessible. As long as 
a handle is locked, Windows’ memory manager will be confronted with 
an immovable object in memory, hampering its ability to make the 
best use of your available memory. In practice, Windows trades 
memory for speed—hobbling the memory manager will slow down the 
applications running under Windows. As soon as you no longer need 
to reference a block of memory, its handle should be passed to 
GlobalUnlock. This doesn’t deallocate the memory in question— 
subsequent calls to GlobalLock will make it accessible again. It just 
allows Windows to move your memory around if need be. 

If you imagine an application that loads and displays an image—a 
number of them will turn up later in this book—you can see how 
handle-based memory works. Having called CreateDIB to allocate and 
initialize a device-independent bitmap, this viewer would have to lock 
the bitmap in memory to write the uncompressed image data to it, and 
then lock it again to copy the image data to your screen. For the rest 
of its time, however, the viewer would have no need to directly access 
its bitmap—leaving it unlocked won’t upset Windows memory 
management. 

It’s particularly important to use handle-based memory when you’re 
dealing with bitmaps, as they tend to be very large objects. If they’re 
locked in memory for a protracted period, they can be expected to 
have a noticeable effect on Windows’ performance. 
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There are circumstances in which you’ll need small memory buffers for 
a very short time in a Windows application. For example, the 
functions that unpack graphic files, to be discussed throughout this 
book, usually need a buffer one line long to unpack image data into. In 
this case, if handle-based memory were used, the buffer would be 
allocated, immediately locked, used, immediately unlocked, and freed. 
The fact that the buffer in question is referenced by a handle rather 
than a pointer wouldn’t help Windows very much, as it would be 
locked for its entire existence. 

Small fixed buffers that will exist for a short time can be allocated such 
that they stay locked in memory for their entire duration. In this book, 
such buffers are allocated by the function FixedGlobalAlloc and freed 
by the function FixedGlobalFree. 

You might well look at all this and wonder why the more conventional 
malloc and free functions couldn’t be used to allocate small fixed 
buffers. In fact, they can be in the 32-bit Windows environment— 
FixedGlobalAlloc and FixedGlobalFree evaluate out to malloc and 
free if you’re writing a 32-bit application. Things are a bit more 
complicated under the 16-bit environment of Windows 3.1. 

A 16-bit Windows application has severe pointer schizophrenia—it will 
be discussed in greater detail later in this chapter. To run large 
applications in a memory structure that doesn’t really know what to do 
with them, 16-bit Windows application regard memory as being split 
between a local data segment and the global memory pool of 
Windows. The local data segment of a Windows application includes 
its stack, any static data it requires and its local memory heap. The 
local memory heap is what is referenced by calls to malloc. 

A 16-bit segment can be no larger than 64 kilobytes. In fact, because 
the local segment must also support an application’s stack and static 
data, calls to malloc shouldn’t expect to be able to allocate anything 
like 64 kilobytes. If you write a 16-bit Windows application that 
allocates memory through malloc —that is, that allocates memory in 
the local data segment—you’ll probably eventually come across one of 
Windows’ nastier tricks. Your application will run out of memory even 
though the global memory heap has memory to burn. 






If you write a 16-bit Windows application, the FixedGlobalAlloc 
evaluates out to a weird call to GlobalAlloc, which causes it to return 
a locked pointer, rather than a handle. This means that the pointer 
returned by FixedGlobalAlloc in a 16-bit Windows application will 
point to a locked memory buffer in the global heap. Such buffers are 
not limited by the size of the local memory heap for your application. 
They are, however, equivalent to locked memory handles, and as such 
should be allowed to remain in existence no longer than is necessary. 

Because 32-bit applications under Windows don’t get involved with 
segments, none of the foregoing applies to them. A pointer returned 
by malloc in a 32-bit Windows application always points to global 
memory, and such a pointer can reference an object as large as your 
computer has available physical memory for. 

Device-independent bitmaps 
under Warp 

IBM’s OS/2 Warp environment shares some common antecedents 
with Windows, and as such, it’s not uncommon to find things handled 
similarly in both environments. Device-independent bitmaps, for 
example, turn up in similar contexts in both Windows and Warp, 
although they’ll turn out to be used somewhat differently. 

Under Warp, device-independent bitmaps consist of a 
BITMAPINF0HEADER2 object followed by an array of RGB2 objects 
to define whatever palette colors are required. Here’s what the header 
looks like: 

typedef struct { 

ULONG cbFix; 

ULONG cx; 

ULONG cy; 

USHORT cPlanes; 

USHORT cBitCount; 

ULONG ulCompression; 

ULONG cblmage; 

ULONG cxResolution; 

ULONG cyResolution; 

ULONG cclrUsed; 

ULONG cclrlmportant; 
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USHORT usUnits; 

USHORT usReserved; 

USHORT usRecording; 

USHORT usRendering; 

ULONG cSizel; 

ULONG cSize2; 

ULONG ulColorEncoding; 

ULONG ulldentifier; 

} BITMAPINF0HEADER2; 

typedef BITMAPINF0HEADER2 *PBITMAPINF0HEADER2; 

Not all the fields in a BITMAPINFOHEADER2 object are useful in the 
context of this book. Here are the ones you’ll want to know about: 

cbFix —This is the size of the BITMAPINFOFIEADER2 object. It 
should be set to sizeof(BITMAPINFOHEADER2). 

CX —This is the horizontal dimension of the bitmap in pixels. 

cy —This is the vertical dimension of the bitmap in pixels. 

cPIanes —This is always set to one. 

cBitCount —This is the number of bits of color depth of the bitmap. 
As with a Windows bitmap, it can be 1, 4, 8, or 24. 

Note that OS/2 allows a BITMAPINFOFIEADER2 object to be 
truncated after the cBitCount field. It’s important to check the cbFix 
field to see how much of a BITMAPINFOP1EADER2 object is actually 
valid if your application didn’t create the BITMAPINF0PIEADER2 
objects in question. This won’t be an issue in the context of this book. 

An RGB2 object, the equivalent of an RGBQUAD under Windows, 
looks like this: 


typedef struct { 
BYTE bBlue; 

BYTE bGreen; 

BYTE bRed; 

BYTE fcOptions; 

} RGB2; 

typedef RGB2 *PRGB2; 









As with Windows, it’s convenient to have a set of macros available to 
access the fields of a BITMAPINF0HEADER2 object. In fact, because 
the macros have the same names, porting functions that use device¬ 
independent bitmaps between Windows and Warp applications is 
relatively simple. Here are the macros for Warp: 

#define LPBwidth(lpbi) ((unsigned int)lpbi->cx) 

#define LPBdepth(lpbi) ((unsigned int)lpbi->cy) 

#define LPBbits(lpbi) ((unsigned int)lpbi->cBitCount) 

#define LPBIinewidth(lpbi) \ 

(WIDTHBYTES((DWORD)lpbi->cx*(DWORD)lpbi->cBitCount)) 

#define LPBcolormap(lpbi) (PRGB2)((LPSTR)lpbi+lpbi->cbFix) 

#define LPBcolors(lpbi) \ 

(lpbi->cBitCount > 8 ? 0 : (l<<lpbi->cBitCount)) 

#define LPBimage(lpbi) \ 

((char *)lpbi+lpbi->cbFix+\ 

(long)LPBcolors(lpbi)*sizeof(RGB2)) 

Note that the LPBcolors macro decides how many palette entries are 
available in a bitmap based on the actual color depth, rather than by 
looking at the colrUsed field of the header. This allows for truncated 
BITMAPINFOHEADER2 objects—while they won’t turn up in this 
book, it’s safer to create the macro this way in case it subsequently 
finds itself pressed into service with bitmaps of unknown origin. 

The CreateDIB function discussed earlier in this chapter to create 
Windows device-independent bitmaps works in precisely the same way 
under Warp, except that some of the field names are different. I 
should note that the examples in this book handle OS/2 memory a bit 
differently—while I’ve defined an object called HANDLE in the OS/2 
examples to keep the code similar, Warp actually manages its memory 
somewhat differently than does Windows. In this book, a HANDLE 
object under Warp is just a pointer, and memory blocks are allocated 
as fixed objects. The GlobalLock and GlobalUnlock I’ve defined for 
the OS/2 versions of the libraries and example functions herein are 
stubs and don’t do anything beyond keeping various elements of 
source code readily portable between the two environments. 

You might want to change this—OS/2’s memory management is more 
flexible than that of Windows but is significantly more complex to 
work with. It’s beyond the scope of this book to get deeply into it. 
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Tales of segments, pointers, 
integers, and madness 


Some of the things to be discussed in this section are the stuff of 
nightmares, and you could be forgiven wanting to skip it all. If you’re 
planning to write applications exclusively for Warp or for 32-bit 
Windows, you can probably safely do so. Authors of 16-bit Windows 
software are cautioned to become familiar with these little nasties— 
they’re not very pleasant, but they’re crucial to the way 16-bit 
applications run under Windows. 

Should you not have kept up with the numerology, Windows 3.1 and 
Windows 3.11, also called Windows for Workgroups, are 16-bit 
operating systems, and applications that run under them are expected 
to be 16-bit applications. Some while back, Microsoft released a bolt- 
on 32-bit extension package for Windows 3.1 called WIN32S, which 
lets it run 32-bit applications, albeit rather slowly. 

Windows NT and Windows 95 are both 32-bit environments, which 
means that they’ll run either 16- or 32-bit applications. The OS/2 
Warp operating system is also a 32-bit environment—it will run 32-bit 
applications, although they must have been written for OS/2, not for 
Windows. As of this writing, Warp comes with a 16-bit Windows 
emulator, making it capable of pretending to be Windows 3.1 and, as 
such, running 16-bit Windows applications as well. Warp’s Windows 
simulation is quite slow and none too stable. 

The distinction between 16- and 32-bit environments usually isn’t all 
that clear, except that more bits seems like it ought to be a good idea. 
This section will get into the grotty details and deal with how pointers 
and integers and several other commonly encountered programming 
objects differ between them. 

A long time ago, when knights were bold and maidens fair and 64 
kilobytes was more memory than anyone could think of a use for, the 
address space in a computer was linear. This meant that it was 
addressed by a single 16-bit register and went from byte number zero 






through to byte number 65535 with the expected number of bytes in 
between. 

After a while, people found that there were all sorts of potential uses 
for more than 64 kilobytes of memory, and a new generation of 
processors was developed to address it. The processors in question, 
called the 8088 and 8086, were the brains behind the first IBM PC 
computers. They could address up to a megabyte of memory. 

The catch in creating these processors was that their developer, Intel, 
didn’t have the technology to implement wide enough address registers 
to address a whole megabyte of memory at once and still have the 
beast run faster than a mechanical adding machine. As such, they 
devised the idea of segmented memory. It got around the problem, 
and in a sense, it made the best use of what was at the time some 
pretty slow chip technology. 

Here’s how segmented memory works. Martians didn’t design this to 
keep humans confused and helpless prior to an invasion, however 
much it might seem otherwise. 

Segmented memory uses two 16-bit registers to address a megabyte of 
memory by dividing the address space into segments. A segment is 64 
kilobytes of memory, and each segment is offset from the one before it 
by 16 bytes, or one page. A bit of calculator action will confirm that 
65,536, the largest number that can be stored in a 16-bit register, 
multiplied by 16, the size of one page, works out to 1,048,576, or 
one megabyte to a computer. The segments overlap, of course. 

An address in segmented memory, then, consists of a segment value 
to select which segment to start with and an offset value to define how 
far into the segment the location in question resides. You’ll find 
addresses of this sort written like this: 

A000:0100H 

This means that the segment in question is A000H and the offset from 
this segment is 0100H. It’s easy to convert this into a linear address— 
the foregoing pointer points to A000H x 16 + 0100H, or 655,616 








decimal. It’s also typically of no use to do this, however, as you can’t 
deal with segmented memory using linear addressing. 

There are a number of important consequences to this sort of 
addressing—not all of them bad, but none of them easy to work with. 
The first one is that multiple pointers having different values in their 
segment and offset registers can address the same physical location in 
memory. For example, the location 0000:001QH references the 16th 
byte in memory—it’s 16 bytes offset from the base of the Oth 
segment. The location 0001:0000H also references the 16th byte in 
memory. In the second case, it’s the Oth byte of the first segment in 
memory. Recall that memory segments are removed from each other 
by 16 bytes. 

The possibility of multiple distinct pointers pointing to the same place 
can make the prospect of comparing pointers somewhat treacherous. 
You can get around this, of course, by normalizing all the pointers; 
that is, fiddling them such that their offset values are as small as 
possible. This adds a level of complexity to some types of software. 

One of the advantages to a segmented memory environment is that 
software can be written using single 16-bit registers to address code 
and objects if the software in question is small enough. A program in 
which all the code and data required can fit in a single segment, called 
a small model program, can ignore segments entirely and address 
everything with 16-bit pointers, called near pointers. This will improve 
the performance of the software in question. 

The catch to this is that larger programs that want to address lots of 
code and data have to do so using 32-bit segment and offset pointers 
to address everything, called far pointers, which are relatively slow. 

Here’s another catch inherent in segmented memory. The largest 
object that can be addressed by adding integer offsets to a far pointer 
will be the size of one segment, or 64 kilobytes. Adding values larger 
than this will cause the pointer to wrap around past the Oth byte in 
the segment. To get around this, objects larger than one segment must 
be addressed using huge pointers. A huge pointer is a far pointer, but 
every time its value is altered, it’s converted into a linear address, 
adjusted with a new offset and then converted back into normalized 











segment and offset values. This allows huge pointers to address objects 
larger than a segment, albeit at a considerable speed penalty. 

A 16-bit Windows application lives in this sort of segmented alternate 
universe, and Windows adds a few complexities of its own to it. The 
architecture of a 16-bit Windows application makes several important 
trade-offs between flexibility and speed in the way Windows software 
can use its memory space. 

In a 16-bit environment, the pool of memory available to run 
applications and store large objects is called global memory. It spans 
multiple segments, of course. When an application loads, its code 
segments are stored in as many discrete memory segments as it 
requires, and it then creates an additional segment, called its local 
data segment. As was touched on earlier in this chapter, the local data 
segment stores an application’s stack, static data, and its local heap. 
We’ll get back to the latter in a moment. 

Windows applications are usually written using the medium memory 
model for a 16-bit environment. This means that all pointers default to 
being near unless you override them. Near pointers assume that 
whatever they’ll be asked to point to will reside in the local data 
segment—you can think of a near pointer as being a segment and 
offset value in which the segment is always that of the local data 
segment, and as such need not be explicitly stored. 

This allows a lot of things to be handled very elegantly in a 16-bit 
Windows application—and creates no end of problems, as you might 
expect. For example, because the stack resides in the local data 
segment, and as automatic local variables and function arguments are 
allocated on the stack, near pointers can point to local variables and 
passed arguments. Here’s an example of this: 

void CrushYourPoodle(char *Flat) 

{ 

char *pFlat; 
pFlat=Flat; 

} 

This will work because the object Flat is on the stack, and hence is in 
the local data segment. 
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Also as was touched on earlier, the conventional C function malloc 
and its kindred memory allocation calls allocate memory out of the 
local data segment and, as such, always return near pointers. Because 
the local heap is whatever’s left over after the application stack has 
been created and the application’s local static data has been seen to, 
it’s unwise to assume that malloc will have access to very much 
memory. In fact, for the sorts of applications that will turn up in this 
book, it’s a very bad idea to use malloc at all. 

Here’s where all this pointer juggling starts to look an awful lot like 
trying to keep three chain saws in the air: 

void CrushYourPoodle() 

{ 

char *pFlat; 

/* don't try this at home */ 
pFlat=FixedGlobalAlloc(1000); 

} 

As was discussed earlier, the FixedGlobalAlloc function is a variation 
of malloc that allocates memory from the global memory pool. It 
returns far pointers, as by definition the global memory pool is 
everywhere except where the local data segment resides. In the 
foregoing example, the pFIat pointer is a near pointer, because all 
pointers in a medium model program default to being near. The 
pointer returned by FixedGlobalAlloc is far, but because pFIat isn’t 
wide enough to hold a far pointer, its segment value will be discarded 
and will be assumed to have been replaced by the segment value of 
the local data segment. As such, pFIat will point somewhere 
unpredictable in the local data segment of your application. Writing to 
this pointer might cause the stack for your application to be partially 
corrupted, for example—all in all, something to be avoided. 

Here’s how this function should have been written: 

void CrushYourPoodle() 

{ 

char far *pFlat; 
pFlat=FixedGlobalAlloc(1000); 

} 



In this example, the pFIat pointer has been declared as being far. This 
means that things pointed to it will be slightly slower to access, but 
they can exist anywhere within Windows’ memory space. 

Keep in mind that you can safely assign near pointers to far pointers. 
Assigning far pointers to near pointers is the digital equivalent of 
cordless bungee jumping. 

Here’s another example of pointers conspiring to make your brain 
hurt: 

void CrushYourPoodle() 

{ 

char far *pFlat; 
pFlat=FixedGlobalAlloc(100000); 

} 

This example has FixedGlobalAlloc allocating a block of 100,000 
bytes of memory; that is, more than one segment. It will have no 
difficulty in doing so, and pFIat, being a far pointer, will have no 
difficulty in pointing to it. However, because pFIat is far, you’ll only be 
able to address the first 64 kilobytes of the buffer it points to. 

Here’s how to get around this: 

void CrushYourPoodle() 

{ 

char huge *pFlat; 
pFlat=FixedGlobalAlloc(100000); 

} 

In this final appearance of CrushYourPoodle, the pFIat pointer is 
huge. This tells C to write some additional code into your application 
wherever pFIat turns up to normalize it when its value changes. 

It’s important to use huge pointers in dealing with bitmaps, which are 
often much larger than one segment. 

Under Windows, most objects have pointers defined for them, in some 
cases with variations for the various pointer types that might be 
required. For example, a pointer to a buffer of chars is defined as: 


typedef PSTR *char; 







A far pointer to a buffer of chars is: 


typedef LPSTR far *char; 


This is a commonly used sort of object under Windows. Finally, a huge 
pointer to a buffer of chars is: 

typedef HPSTR huge *char; 


The other important thing to know about 16-bit Windows applications 
is that they often use a machine register to store objects of the type 
int. As such, an int is always 16 bits wide and is in fact equivalent to a 
short int. This can get you into all sorts of trouble because it doesn’t 
take much to make numbers stored as int overflow—the largest value 
that can be stored in a short int is 65,535. For example, the 
WIDTH BYTE macro discussed earlier in this chapter is typically passed 
a value that is the width of a bitmap multiplied by its color depth in 
bits. Neither of these values is likely to come close to overflowing the 
bounds of good taste and 16-bit integers by itself, but they can do so 
when you multiply them together. For example, a true color bitmap 
4096 pixels across would have a line encompassing 98,304 pixels, a 
number too large to be stored in a 16-bit int. Keep in mind that 
multiplying two ints together allows C to do all its calculation using 
simple integers. 

This is a large bitmap, but such images are by no means unheard of. 
They occur on Kodak Photo-CDs, for example. 

In dealing with calculations that might overflow a short integer, it’s 
important to remember to cast the objects involved to long. 

One of the attractions of a 32-bit environment such as Windows 95 or 
Warp is that all of the foregoing will become instantly meaningless. A 
32-bit environment works by placing an 80386 or better processor in 
its linear address mode, in which memory can once again be 
referenced by simple numbers. As such, there are no segments in a 
32-bit application, and all pointers are the same. You can add any 
number you like to a 32-bit pointer and, as such, address objects in 
memory of any size. Because the pointer arithmetic involved is 
inherently easier, 32-bit applications are both smaller and run faster 
than their 16-bit antecedents. 






In fact, you can still only add integers to pointers in a 32-bit C 
program, but because an int is defined as being the width of a machine 
register, and machine registers are 32 bits wide, an int can hold 
numbers as big as a long int could in a 16-bit application. 

If you create an application as a 16-bit program under Windows, you 
can very often recompile it as a 32-bit application with no code 
changes. Windows uses type definitions to make this relatively 
painless. For example, it defines far and huge as being meaningless in 
a 32-bit environment, so for example: 

typedef LPSTR FAR *char; 

evaluates to: 

typedef LPSTR *char; 

for 32-bit applications. There actually are a few subtle API changes 
between 16- and 32-bit Windows—you’ll encounter a few of them 
later in this book. 

There are two important things to keep in mind about the difference 
in size between int in 16- and 32-bit Windows applications. The first is 
that the latter will hold larger numbers, whether you want it to or not. 
Here’s an example of how this can be a bit sneaky. This is how you 
could work out the number of colors to store in the biCIrUsed field of 
a BITMAPINFOHEADER: 


int colors; 
colors = l«bits ; 


At least, that’s how you could work it out for a 16-bit Windows 
application. If colors is a 16-bit object, it will store two if bits is 1, 16 
if bits is 4, 256 if bits is 8, and 0 if bits is 24. This is exactly what 
you’d want it to do, as biCIrUsed should reflect that there are no 
palette entries in a 24-bit device-independent bitmap. This works 
because 1 << 24 is a number too large to store in a 16-bit object, and 
its low-order word is zero. 





This won’t work properly in a 32-bit application. The value 1 << 24 
will fix in a 32-bit int, and the resulting bitmap will think it has a 
palette of 16,777,216 RGBQUAD objects, an unlikely occurrence. 

You could make this code portable by being a bit more specific about 
the sort of integer you had in mind: 

short int colors; 
colors = l«bits ; 

This has defined colors as being a 16-bit integer in either 
environment. If you’ve done a lot of programming either under DOS 
or for Windows 3.1, be careful how you use ints when you port things 
to 32 bits. 

Secondly, keep in mind that the expression sizeof(int) will return two 
if it finds itself in a 16-bit application and four if it’s part of 32-bit 
software. This is important if you’re reading data from a file that exists 
in fixed fields. For example, this data structure will change size 
between 16- and 32-bit applications: 

typedef struct { 
int number; 
int count; 
int poodles; 
int flat_poodles; 

} RECORD; 

This structure will not: 

typedef struct { 
short int number; 

short int count; 

short int poodles; 

short int flat_poodles; 

} RECORD; 

Programmers who have written extensively in C under DOS or for the 
16-bit Windows environment will often ignore the size of int objects in 
moving to 32-bit software—periodically with unpleasant 
consequences. Keep an eye on the little monsters, as they can creep 
up on you from behind. 







Dynamic link libraries: what yon 
don’t know can’t hurt you 

A dynamic link library is a useful bit of Windows and Warp juggling, 
although in many cases for reasons that the authors of these 
environments didn’t foresee. Especially under 16-bit Windows, you can 
use DLLs to cheat around some of the limitations inherent in this 
archaic operating environment. 

In the traditional structure of a C program, all the functions an 
application calls are statically linked. This means that they’re 
hardwired into the application’s executable code and stored as part of 
its EXE file. 

Windows and Warp offer a second approach to handling linking 
selected functions into a calling application, that of dynamic linking. A 
dynamic link library is a block of callable code that exists as a separate 
file, typically with the extension DLL. An application can load DLLs 
after it runs and link the DLL functions with its principal executable 
code. In fact, for the applications of DLLs to be discussed in this book, 
Windows will take care of the grotty details of handling DLLs—you’ll 
be able to treat the functions contained in dynamic link libraries as if 
they were part of your program. 

There are a number of advantages to using dynamic link libraries 
rather than static linked functions. The one that the authors of 
Windows had in mind was that the same dynamic link libraries can be 
called by multiple applications, providing common functions to many 
programs while eliminating a lot of redundant code. In fact, this is less 
often useful than you might think unless you’ll be writing several 
applications with common functions. Conflicts between multiple 
versions of DLLs or DLLs from different applications that happen to 
have the same file names are one of the real banes of Windows. 

The suite of bookware applications on the companion CD-ROM for 
this book illustrates a group of applications that use a common 
collection of DLLs. While this looks really elegant, these applications 




are a dog to maintain. Changes to one of the DLLs often means 
recompiling and re-issuing all the applications that call them. 

There are two inherent advantages in using dynamic link libraries for 
16-bit Windows applications. When a DLL is linked to its calling 
application, it shares the calling application’s stack segment, but not 
its common static data. One of the restrictions on creating 16-bit 
Windows applications is that all the static data, the stack, and the 
heap must fit within one 64 kilobyte segment. If your application 
requires a lot of static data, it can easily run out of elbow room. There 
are all sorts of ways around this problem, of course, but one of the 
obvious ones is to move some of the code that’s dependent on static 
data into separate DLLs, as each DLL has its own 64 kilobyte data 
segment. 

Having said this, keep in mind that static data in a DLL can’t be 
accessed directly by a calling application using conventional near 
pointers. Secondly, a DLL is itself limited to 64 kilobytes of static 
data. This will actually turn up as a genuine problem later in this book, 
when I discuss TIFF files. 

The other useful characteristic of dynamic link libraries for a 16-bit 
Windows application is that they’re always large model programs. This 
means that the default pointer type is always far, rather than near, 
which would be the case for Windows applications compiled in the 
medium model. Several of the libraries that will be discussed in this 
book to read specific commercial graphic file formats were written by 
third parties and were intended for environments other than Windows. 
They don’t allow for the limitations of a medium-model environment. 
You could get around this by going through them and overriding all 
their pointers to far, of course, but this is time-consuming and fraught 
with hazards. A much simpler solution is to pot them in DLLs, 
whereupon all their pointers will automatically become far. 

Storing functions in a DLL, then, allows the bulk of a 16-bit Windows 
application to run using the advantages of the medium memory 
model, with selected portions of the code compiled as large model 
functions. 






If you’ll be writing applications for a 32-bit Windows environment or 
for Warp, the memory-model and data-segment problems that DLLs 
overcome won’t be a problem in the first place, of course. 

Perhaps one of the best things about the DLLs that will turn up in the 
context of this book is that, while you’re free to see how they work 
internally if you want to, there’s no compelling reasons to do so. You 
can treat them as black boxes that can be called by your applications 
to perform various functions with graphic files, and otherwise ignored. 
In this respect, DLLs provide a very convenient interface to 
interchangeable functionality. 

For example, each of the graphic file formats to be discussed in this 
book is handled by a DLL. Each DLL has the same linkable functions, 
although to support different file formats. The ReadGraphicFile 
function accepts a path to a graphic file as its argument and returns a 
handle to a correctly formatted device-independent bitmap when it’s 
done. 

If you write an application and link it to the library that handles GIF 
files, ReadGraphicFile will decode GIF files. If you link it to the library 
that handles JPEG files, ReadGraphicFile will decode JPEG files. The 
call to ReadGraphicFile will look the same to your application in each 
case. 

The mechanism for linking and calling functions from dynamic link 
libraries is actually pretty involved—but you won’t have to bother with 
it, as Windows is happy to do almost all the work for you. Each 
dynamic link library is accompanied by an import library , a small 
static linking library that can be linked to your application at compile 
time. As such, when your application calls ReadGraphicFile, for 
example, it actually calls a stub function the static import library. The 
import library loads the corresponding DLL if necessary and passes 
the call along to it. While DLLs exist separately from the main 
executable files that call them, you can treat them as if they’re just 
another part of your program. 

You’ll get to see this in action in the next chapter of this book. 
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As an aside, there is another way to load and call dynamic link 
libraries. The LoadLibrary function under Windows allows you to load 
a DLL programmatically and then call its functions by name. It’s a bit 
tricky to use, but it’s handy if you’d like to be able to allow your calling 
application to choose its DLLs at run time, rather than at compile 
time. It won’t turn up in the context of this book. It’s used by the 
GraphSaver software included in the bookware applications on the 
CD-ROM of this book to call the library files which perform graphic 
file reads for it, GIFLIB16.DLL, JPGLIB16.DLL, and so on. 

— Using the source code 
for this book 


The companion CD-ROM includes source code for all the example 
applications and the dynamic link libraries in this book. The source 
code resides in \WINBIT for the Windows version of the software and 
in \OS2BIT for the OS/2 version. 

Having bought this book, you have bought the right to use executable 
versions of the software provided as source code herein in your own 
applications without the payment of any further royalties to either the 
author of this book or its publisher. This does not affect any royalties 
or other fees you might have to pay to the copyright holders of any of 
the technologies discussed—you’ll find more about this in chapter 
three. You are also not required to credit this book in your 
application, although you might be required to acknowledge the 
contributors of some of the other technologies used. This will be 
discussed as it comes up. You do not have the right to distribute the 
source code or libraries presented in this book in any form that would 
allow someone who has not bought this book to use them in another 
application. 



















INDOWS is somewhat protective of those hardware resources 
that might be shared by multiple applications but that only 
quantities of one. Somewhere near the top of its list of things 
to guard with the ferocity of a Doberman in tight shorts, the video 
display resources have a special place in its heart. No one gets to 
mess with your monitor unless Windows says it’s all right. 

The reason for this degree of protectiveness will be fairly obvious if 
you think about it. Were each application running under Windows 
empowered to modify the hardware configuration of your screen, all 
the other applications would have to live in a world with display 
characteristics that can’t be counted upon to remain the same. This is 
the sort of thing that might require expensive counseling and therapy 
sessions for your software—all in all, something to be avoided. 

To keep applications from hijacking the video resources of your 
computer, Windows requires that all screen access be handled through 
its GDI calls. This means, for example, that, if you want to paint 
something red in the window for your application, you must negotiate 
with Windows to arrive at a color of red that’s more or less in keeping 
with your requirements and yet still within Windows capacity to 
generate. This might or might not be a simple matter. 

To understand why Windows has such trouble with managing screen 
hardware—and ultimately to appreciate why some of the code to be 
discussed in this chapter will be a lot trickier than it seems as if it 
should be—it’s essential to understand a bit about the underlying 
hardware resources that make PC display systems work. While 
Windows will effectively insulate you from having to fiddle VGA 
registers, change display pages, or move blocks of video memory 
around, you’ll still have to write software that can work within the 
hardware limitations of the displays it might find itself running on. 

This, in fact, is one of the trickier aspects of writing graphic-intensive 
Windows software, by the way. It has to get along with a variety of 
systems with widely differing display characteristics. 
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If you’re creating software to run under OS/2, keep in mind that, 
while OS/2 uses different GPI calls to handle the functions to be 
discussed herein, it’s confronted with the same sorts of hardware 









restrictions. As such, it deals with display access in much the same 
way. A detailed discussion of how Warp gets things done will appear 
later in this chapter. 


Your monitor: 
vacuum with an attitude 


For the sake of this discussion, all the displays that Windows and 
Warp will be asked to drive are VGA cards or supersets thereof. In 
fact, this isn’t true—older display devices probably still exist, awaiting 
the next garage sale, and a few specialized non-VGA cards turn up 
from time to time in areas like medical imaging and desktop 
publishing. Let’s ignore these mutants in an effort to make all the 
following explanation reasonably easy to understand. 

A basic VGA card can display graphics in two modes of interest: 320 
by 200 pixels at 256 colors and 640 by 480 pixels at 16 colors. The 
former mode doesn’t allow for enough screen resolution to display a 
Windows desktop, and as such we’ll ignore it. The 640 by 480 pixel 
graphic mode can handle a Windows desktop, albeit with severely 
restricted color choices. 

Not many standard VGA cards still exist, but this doesn’t mean that 
your applications can count on not having to deal with a 16-color 
display device. When Windows is first installed, it assumes that it’s 
dealing with a standard VGA card in this mode until it’s told 
otherwise. Specifically, users of Windows with better display options 
must explicitly install a suitable Windows screen driver to allow for 
more screen resolution and better color depth. Not all of them do. 

Keep in mind that a system that can display 16,777,216 simultaneous 
colors running with a 16-color Windows screen driver is a 16-color 
system as far as Windows is concerned. Windows sees your display 
hardware through whichever driver is installed in it—if your display 
card can do more than your current Windows screen driver, Windows 
will never know about it until you update the driver. 





As with the basic structure of bitmaps that were discussed in the 
foregoing chapter, the next step up from a 16-color Windows display 
is a 256-color Windows display. At 256 colors, Windows still 
maintains its display as a palette-driven bitmapped device, which 
means that it can select its colors from a potential palette of 
16,777,216, but it can only display 256 of them at a time. 

Windows also supports three common screen color depths that are not 
palette driven: 32,768, 65,536, and 16,777,216 colors. 

Most of the problems that arise surrounding Windows’ use of color are 
involved with color palettes. They all drop conveniently into 
hyperspace if you shift to a high color or true color display driver. 
Sadly, not everyone is likely to do so in the immediate future. 

On a system with a 16-color display, Windows initializes the display 
hardware with a fixed 16-color palette, called the reserved palette. In 
fact, the standard Windows reserved palette has 20 colors—in a 16- 
color environment Windows ignores the latter 4 colors, using dithering 
to simulate them if they’re called for. 

Windows will not allow applications to change its reserved palette, and 
as the entire hardware palette on a 16-color system is occupied by 
reserved colors, the same 16 colors apply to all applications. If an 
application wants to paint something red, it must either use the 
nearest color of red in the reserved palette or use a dithered color 
created by Windows out of its available reserved colors. 

Windows dithering is fast rather than accurate—dithered colors won’t 
fool anyone into thinking they’re looking at reality. 

Displaying photorealistic graphics under Windows running a 16-color 
display adapter will entail either serious dithering or radical color 
shifts, as illustrated in Fig. 2-1. 

If Windows’ dogma about reserved colors seems a bit inflexible, it’s 
important to keep in mind what could happen if multiple concurrent 
applications were empowered to set the hardware palette to their 
liking. Consider what would appear on your screen if Windows 
attempted to display a system dialog after its foreground application 
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A photorealistic image (a) displayed 
on a 16-color Windows display 
remapped (b) and dithered (c). Very 
post-modernist, but less than wholly 
attractive. 


c 

had set all the palette registers to almost identical shades of light gray. 
The dialog, like the rest of the screen, would be gray on gray, and 
probably pretty difficult to read. Windows requires that it have a 
minimal list of colors it can count on for drawing things like window 
borders, buttons, and other system objects. 

If you step up to a 256-color Windows screen driver, the color 
situation will get a lot less claustrophobic. Windows will still reserve a 


Figure 2-1 







Figure 2-2 




palette of 20 colors, but this leaves 236 palette entries that can be set 
by the current foreground application. If you attempt to display a 256- 
color image under these conditions, Windows’ palette manager will 
juggle the color palette of the image to work in the Windows reserved 
color palette, and in most cases, you’ll never notice that some of the 
colors in your image have been remapped a bit. 

There are some potential problems with this arrangement, especially if 
you’re working with sophisticated imaging software, but it comes off 
surprisingly well in less demanding situations. 

One of the things that can be a meaningful problem in displaying 256- 
color bitmaps on a 256-color display adapter under Windows is the 
possibility of conflicting palettes in multiple bitmaps. This is illustrated 
in Fig. 2-2. In this example, two image file viewers have been 
launched to display different images, each with its own color palette. 
The foreground application defines the 236 available palette entries, 



Two viewers, one palette, cream of pixel soup. 













which means that the viewer behind it must work with a palette not its 
own. Its image will be displayed in really badly chosen colors. 

Note that, if you were to click on the rearmost of the two viewers in 
Fig. 2-2 to bring it to the foreground, it would seize the palette and 
display its image correctly at the expense of the first viewer. Windows 
can correctly display 256-color images on a 256-color display driver, 
but only one at a time. 

Applications that must display multiple disparate bitmaps at once 
under Windows deal with this situation by remapping or dithering all 
the bitmaps to a common palette. It’s beyond the scope of this book 
to get into the nuances of this procedure—you can find more about it 
in my book Multimedia Programming for Windows, published by 
McGraw-Hill. 

Windows display drivers that support high color and true color don’t 
have palettes, and as such none of the foregoing matters. Applications 
are free to paint things in their windows using whatever colors they 
require. Windows never dithers colors on a high color or true color 
system, multiple bitmaps with differing palettes can be displayed 
without difficulty, and cream of pixel soup is never on the menu. If 
you were prepared to require that everyone who will be using your 
applications have such a display card in your system, the code to 
display bitmaps therein would be worlds simpler. 

Display contexts: here's where 
the mutants come out 

The data in your display adapter’s video memory is structured in a way 
that makes sense to the display hardware that will use it and, 
indirectly, that made sense to the author of its Windows screen driver. 
Windows itself does not understand how this data works, nor would it 
want to if you were to tell it. When it wants to display something on 
your screen, it presents the object in question to your display driver, 
which takes care of the grotty details. 







Windows considers the surface of your monitor—albeit as filtered 
through its current display driver—to be a device context. This means 
that it’s a bitmap upon which you could draw things if you knew how it 
was structured and where it was located—things drawn on this magic 
bitmap would appear on your screen. Windows will tell you neither of 
these things, of course. However, it will accept requests from your 
software to have it draw things on the bitmap. 

A device context is an ineffable object under Windows, and you can’t 
work with one directly. Windows will provide you with handles to its 
device contexts, called HDC objects, but it does so with the 
understanding that you may not try to mess with whatever an HDC 
references. 

To display a bitmap in an application window, you must make its color 
palette and Windows’ color palette come to an agreement regarding 
the colors to be used, then you must allow Windows to convert the 
format of your bitmapped data into the format of the bitmapped data 
in its display device context. Taking care of the palette is relatively 
simple and is properly called realizing your bitmap’s palette. In fact, 
realizing a palette can do one of a number of things behind your back, 
depending upon the relative color depths of the bitmap in question 
and your current Windows display driver. This might involve Windows 
plotting an awesome retribution and remapping strategy if you attempt 
to display a bitmap with more color depth than your display adapter 
can support directly—a special place in hell is reserved by Windows for 
applications that ask to display true color images on a 16-color 
display—or it might involve Windows doing absolutely nothing if your 
display driver supports high color or true color. It’s sufficient to know 
that, after realizing your bitmap’s palette, Windows can be expected to 
handle its colors as well as can be expected, allowing for your display 
driver. 

Having gotten the palettes playing nicely together, you must massage 
the data in your bitmap such that it conforms to the data structure of 
the HDC for Windows display, then tell Windows to paint the 
massaged data to your screen. Windows offers two distinct approaches 
to handling this, and it’s important to keep them straight when you 
write applications that will deal with bitmaps. 
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The simplest GDI call to display bitmaps is SetDIBitsToDevice— 
although, with a name like that, it certainly doesn’t look very simple. 
You can pass it the HDC of the device you want to display a bitmap 
on—in this case, your screen—and a pointer to a device-independent 
bitmap of the sort discussed in the previous chapter. It will take care 
of massaging the data between formats. This is the easiest way to 
display a bitmap under Windows and incidentally is the one that will 
turn up later in this chapter. It also makes the most efficient use of 
Windows’ memory, a worthwhile consideration if you’re dealing with 
huge bitmaps. 

Here’s how it works. In this example, the Ipbi object is assumed to 
point to a device-independent bitmap. 

SetDIBitsToDevice(hdc, 

destx, 

desty, 

LPBwidth(Ipbi), 

LPBdepth(lpbi), 
sourcex, 
sourcey, 
firstline, 

LPBdepth(lpbi), 

LPBimage(lpbi), 

(LPBITMAPINFO)lpbi, 

DIB_RGB_COLORS); 

The arguments to SetDIBitsToDevice define the source and 
destination bitmaps to be copied and the rectangular area involved. 
They are: 

hdc—A handle to the device context for your screen. 

destx and desty —The location of the upper-left corner of the 
destination rectangle in the window represented by hdc. 

LPBwidth(lpbi) and LPBdepth(lpbi) —The dimensions of the bitmap 
to be copied. 

sourcex and sourcey —The location of the upper-left corner of the 
source rectangle to copy the bitmap from. 
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firstline —The first line number of the bitmap data. This is usually zero. 

LPBdepth(lpbi) —The number of lines in the bitmap. 

LPBimage(lpbi)—A pointer to the bitmap data. 

(LPBITMAPINFO)lpbi—A pointer to a BITMAPINFO object that 
defines the source bitmap’s palette. 

DIB_RGB_COLORS —A flag that tells SetDIBitsToDevice that the 
color palette it’s been passed is a list of RGBQUAD objects. 

The catch to using SetDIBitsToDevice is that it’s relatively slow, as it 
must swab its bitmap data on the fly. Should you be interested in 
animating small bitmaps under Windows, you’ll probably want to look 
at the second display option Windows offers. This is how it works— 
this example assumes that there’s a pointer to a device-independent 
bitmap called Ipbi. 

HBITMAP hBitmap,hOldBitmap; 

HDC hMemory DC; 

hBitmap=CreateDIBitmap (hdc, lpbi, CBM_INIT,LPBimage (lpbi) , 

(LPBITMAPINFO)lpbi,DIB_RGB_COLORS); 

hMemoryDC=CreateCompatibleDC(hdc); 
h01dBitmap=Select0bject(hMemoryDC,hBitmap); 

BitBlt(hdc, 


o, 

//x dest 

o, 

//y dest 

LPBwidth(lpbi), 

//width 

LPBdepth(lpbi), 

//depth 

hMemoryDC, 

0, 

//x source 

0, 

SRCCOPY); 

//y source 


In this example, the CreateDIBitmap call returns a handle to a device¬ 
dependent bitmap that is compatible with the internal bitmap structure 
of the HDC object passed to it. The arguments to CreateDIBitmap 
work as follows: 

hdc —A handle to the device context for your screen. 






Ipbi—A pointer to a BITMAPINFOHEADER object that defines the 
source bitmap. 

CBMJNIT—A flag to tell CreateDIBitmap that it will be expected to 
initialize the bitmap it creates with the data passed to it. 

LPBimage(lpbi) —A pointer to the bitmap CreateDIBitmap is 
expected to initialize its new bitmap with. 

(LPBITMAPINFO)lpbi—A pointer to a BITMAPINFO object that 
defines the source bitmap’s palette. 

DIB_RGB_COLORS —A flag that tells CreateDIBitmap that the color 
palette it’s been passed is a list of RGBQUAD objects. 

Having created a suitable bitmap, the CreateCompatibleDC function 
returns a synthetic HDC to select it into, because the BitBIt function 
to be used in a moment can only copy between device contexts. The 
SelectObject function selects the new device-dependent bitmap into 
the synthetic device context. 

The BitBIt function does the work of actually displaying your bitmap. 
Its first argument is the HDC of the destination device, in this case 
your screen. The second and third arguments define the upper-left 
corner of the rectangle it should occupy. The forth and fifth argument 
define the width and depth of the bitmap to be copied. The sixth 
argument is the HDC of the source bitmap, and the seventh and 
eighth argument define the upper-left corner of the rectangle to be 
copied from it. The ninth argument is a constant that tells BitBIt how 
to combine the source and destination pixels—the SRCCOPY value 
tells it to paint over the destination pixels with the source pixels. 

While it’s probably not obvious here, the BitBIt function can be used 
to copy sections from a larger source bitmap and paint them 
anywhere in a destination window. If you look at the GraphSaver 
application in the Bookware library on the CD-ROM that accompanies 
this book, you’ll see BitBIt in action in this capacity. 
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VIEWER: 

a bitmap display application 

Graphic viewers are the simplest sorts of applications to deal with 
bitmapped graphics. The basis of the software to be discussed in the 
later chapters of this book is a simple viewer that can be linked to 
each of the format-specific libraries. It does the sorts of things you can 
do with whole bitmaps under Windows, including: 

Unpacking commercial graphic files into bitmaps. 

Displaying bitmaps. 

^ Writing bitmaps back to commercial graphic files. 

Displaying information about bitmaps. 

Printing bitmaps. 

Copying bitmaps to the clipboard. 

Pasting bitmaps from the clipboard. 

Figure 2-3 illustrates the generic viewer in action. 

The viewer knows nothing about specific graphic file formats—it must 
be linked to one of the dynamic link libraries to be discussed later in 
this book to become a GIF viewer, a JPEG viewer, a PNG viewer, and 
so on. As such, the viewer by itself would be left with several 
unresolved externals were it to be compiled without the import library 
of a graphic format DLL. 

Figure 2-4 is the source code for the viewer. Note that the source 
code, project files, and all the other bits you’ll need to compile the 
programs in this book can be found on the companion CD-ROM for 
this book. 

There’s very little happening in VIEWER.GPP that won’t be familiar if 
you’ve done some C programming for Windows. The WinMain 
function calls CreateMainWindow, which creates the application 
window and processes its messages. 
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Several instances of the viewer application 


Windows and OS/2 Bitmapped Graphics 
Viewer 


Copyright (c) 1995 Alchemy Mindworks Inc 


#include <windows.h> 
#include <stdio.h> 
#include <stdlib.h> 


The source code for VIEWER. CPP. 
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m : 

: ; 



#include <ctype.h> 
#include <string.h> 
#include <commdlg.h> 
#include "winbit.h" 


#define FILE_OPEN 101 
ttdefine FILE_SAVEAS 102 
#define FILE_GETINFO 103 
#define FILE_PRINT 104 
#define FILE_NOTICE 105 

#define FILE_CLOSE 106 
#define FILE_EXIT 199 

#define EDIT_CUT 201 
#define EDIT_COPY 202 
#define EDIT_PASTE 203 


#define HELPM_INDEX 901 
#define HELPM_USING 902 
#define HELPM_ABOUT 999 


#define APPLICATION "Viewer 


#define SetFileOpen() { HMENU hmenu=GetMenu(hwnd);\ 

if(image) {\ 

EnableMenuItem(hmenu, EDIT_COPY,MF_ENABLED ! MF_BYCOMMAND) ; \ 
EnableMenuI tem (hmenu, EDIT_CUT, MF_ENABLED ! MF_BYCOMMAND) ; \ 
Enab 1 eMenu11 em (hmenu, FILE_SAVEAS, MF_ENABLED ! MF_BYCOMMAND) ; \ 
Enab 1 eMenu 11 em (hmenu, FI LE_PRINT, MF_ENABLED ! MF_B YCOMMAND) ; \ 

}\ 

else {\ 

EnableMenuItem(hmenu,EDIT_COPY,MF_GRAYED ! MF_BYCOMMAND);\ 
Enabl eMenu I tem (hmenu, EDIT_CUT, MF_GRAYED ! MF_BYCOMMAND) ; \ 
EnableMenuI tem (hmenu, FILE_SAVEAS, MF_GRAYED ! MF_BYCOMMAND) ; \ 
Enabl eMenuI t em (hmenu, FI LE_PRINT, MF_GRAYED ! MF_BYCOMMAND) ; \ 

}\ 


LRESULT FAR PASCAL SelectProc(HWND hwnd,unsigned int message, 
WPARAM wParam, LPARAM lParam) ; 

HANDLE CreateCompatiblelmage(HANDLE source); 

HDC GetPrintOptions(HWND hwnd); 

WORD Dolnfo(HWND hwnd,LPSTR path); 

WORD SetScrollBars(HWND hwnd,HANDLE handle); 

WORD HandleDialogScrollMessage(HWND hwnd,WPARAM wParam, 

LPARAM lParam,WORD type) ; 

WORD GetDisplayBits(); 
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int GetFileName(HWND hwnd,LPSTR path); 
int PutFileName(HWND hwnd,LPSTR path); 

int CreateMainWindow(HANDLE hlnstance,HANDLE hPrevInstance, 
LPSTR lpszCmdParam,int nCmdShow); 

void CentreWindow(HWND hwnd); 

void DoHelp(HWND hwnd,LPSTR keyword); 

void SetHelpSize(HWND hwnd); 

void MakeHelpPathName(LPSTR szFileName); 

void DoMessage(HWND hwnd,LPSTR message); 

void DoAbout(HWND hwnd); 

char szAppName[]=APPLICATION; 

char filename[STRINGSIZE+1]; 

HANDLE image=NULL; 

HANDLE displayimage=NULL; 

HANDLE hlnst; 

HWND nextViewer; 

ttpragma warn -par 

int PASCAL WinMain(HANDLE hlnstance,HANDLE hPrevInstance, 
LPSTR lpszCmdParam,int nCmdShow) 

{ 

hlnst=hlnstance; 

return(CreateMainWindow(hlnstance,hPrevInstance, 
lpszCmdParam, nCmdShow) ) ; 

} 

LRESULT FAR PASCAL SelectProc(HWND hwnd,unsigned int message, 
WPARAM wParam,LPARAM lParam) 

{ 

HANDLE handle; 

HCURSOR hSaveCursor,hHourGlass; 

PAINTSTRUCT ps; 

HDC hdc; 

HMENU hmenu; 

char b[STRINGSIZE+1]; 

switch(message) { 

case WM_CREATE: 

return(FALSE); 
case WM_DRAWCLIPBOARD: 
case WM_CHANGECBCHAIN: 

hmenu=GetMenu(hwnd); 

if(IsClipboardFormatAvailable(CF_DIB)) 
EnableMenuItem(hmenu,EDIT_PASTE, 

MF_ENABLED ! MF_BYCOMMAND); 

else 

EnableMenuItem(hmenu,EDIT_PASTE, 
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MF_GRAYED ! MF_BYCOMMAND); 

if((HWND)wParam==nextViewer) 

nextViewer=(HWND)LOWORD(1Param); 
else if(nextViewer != NULL) 

SendMessage(nextViewer,message, 
wParam,lParam); 
return(FALSE); 
case WM_SYSCOMMAND: 

switch(wParam & OxfffO) { 
case SC_CLOSE: 

SendMessage(hwnd,WM_COMMAND, 

FILE_EXIT,OL); 
break; 

} 

break; 

case WM_SIZE: 

SetScrollBars(hwnd,image); 

InvalidateRect(hwnd,NULL,TRUE); 
return(FALSE); 
case WM_DESTROY: 

SendMessage(hwnd,WM_COMMAND,FILE_CLOSE,OL); 
ChangedipboardChain(hwnd,nextViewer) ; 
MakeHelpPathName(b); 

WinHelp(hwnd,b,HELP_QUIT,NULL); 

PostQuitMessage(0); 
return(FALSE); 
case WM_VSCROLL: 

if(HandleDialogScrollMessage(hwnd,wParam, 
lParam,SB_VERT)) 

InvalidateRect(hwnd,NULL,FALSE); 
return(FALSE); 
case WM_HSCROLL: 

if(HandleDialogScrollMessage(hwnd,wParam, 
lParam,SB_HORZ)) 

InvalidateRect(hwnd,NULL,FALSE); 
return(FALSE); 

case WM_PAINT: 

hdc=BeginPaint(hwnd,&ps); 

if(displayimage !=NULL) { 

if(!ShowDib(hdc,displayimage, 

(WORD)GetScrollPos(hwnd,SB_HORZ), 

(WORD)GetScrollPos(hwnd,SB_VERT))) 
MessageBeep(0); 

} 

else { 

if(image != NULL) { 

if(!ShowDib(hdc,image, 

(WORD)GetScrollPos(hwnd,SB_HORZ), 
(WORD)GetScrollPos(hwnd,SB_VERT))) 
MessageBeep(0); 
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} 

} 

EndPaint(hwnd,&ps); 
return(FALSE); 
case WM_COMMAND: 

switch(wParam) { 

case EDIT__COPY: 

if(!CopyPictureToClipboard(hwnd,image)) { 

DoMessage(hwnd, 

"Error copying image to the clipboard"); 
return(FALSE); 

} 

else return(TRUE); 
case EDIT_CUT: 

if(S endMe s s age(hwnd,WM_COMMAND, 

EDIT_COPY,OL)) 

SendMessage(hwnd, 

WM_COMMAND,FILE_CLOSE,OL); 
break; 

case EDIT_PASTE: 
if((handle= 

PastePictureFromClipboard(hwnd)) != NULL) { 

Wait(); 

SendMessage(hwnd,WM_COMMAND, 

FILE_CLOSE,OL); 
image=handle; 

InvalidateRect(hwnd,NULL,TRUE); 
SetScrollBars(hwnd,image); 

SetFileOpen(); 
displayimage= 

CreateCompatiblelmage(image); 

NoWait(); 

} else 

DoMessage(hwnd, 

"Error pasting image from the clipboard"); 
break; 

case HELPM_INDEX: 

MakeHelpPathName(b); 

WinHelp(hwnd,b,HELP_INDEX,NULL); 
break; 

case HELPM_USING: 

WinHelp(hwnd,"",HELP_HELPONHELP,NULL); 
break; 

case HELPM_ABOUT: 

DoAbout(hwnd); 
break; 

case FILE_OPEN: 

SendMessage(hwnd,WM_COMMAND,FILE_CLOSE,OL); 
if(GetFileName(hwnd,b)) { 

Wait(); 

if((image=ReadGraphicFile (b) )==NULL) { 
GetError(b); 
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DoMessage(hwnd,b); 

} 

InvalidateRect(hwnd,NULL,TRUE); 
SetScrollBars(hwnd,image); 

SetFileOpen(); 

displayimage=CreateCompatibleImage(image) 
NoWait(); 

} 

break; 

case FILE_SAVEAS: 

lstrcpy(b,"untitled."); 
lstrcat(b,GetFileExtension()); 
strlwr(b); 

if(PutFileName(hwnd,b)) { 

Wait(); 

if(!WriteGraphicFile(b,image)) { 

GetError(b); 

DoMessage(hwnd,b); 

} 

NoWait(); 

} 

break; 

case FILE_GETINFO: 

if(GetFileName(hwnd,b)) 

Dolnfo(hwnd,b); 
break; 

case FILE_CLOSE: 

if(image ! = NULL) GlobalFree(image); 
image=NULL; 

if(displayimage != NULL) 

GlobalFree(displayimage); 
disp1ayimage=NULL; 

SetScrollBars(hwnd,image); 

SetFileOpen(); 

InvalidateRect(hwnd,NULL,TRUE); 
break; 

case FILE_NOTICE: 

DoMessage(hwnd,GetNotice()); 
break; 

case FILE_PRINT: 

if((hdc=GetPrintOptions(hwnd)) != NULL) { 

Wait(); 

if(!PrintBitmap(hdc,image)) 

DoMessage(hwnd,"Error printing"); 
DeleteDC(hdc); 

NoWait(); 

} 

break; 

case FILE_EXIT: 

SendMessage(hwnd,WM_CLOSE,0,OL); 
break; 
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} 


return(FALSE); 


return(DefWindowProc(hwnd,message/WParam,lParam)); 


HDC GetPrintOptions(HWND hwnd) 

{ 

PRINTDLG pd; 

char b[STRINGSIZE+1]; 

int r; 


memset((char *)&pd,0,sizeof(PRINTDLG)); 

GetWindowText(hwnd,b,STRINGSIZE); 

pd.lStructSize=sizeof(PRINTDLG); 
pd.hwndOwner=hwnd; 

pd.Flags=PD_RETURNDC ! PD_NOPAGENUMS ! PD_NOSELECTION; 

r=PrintDlg(&pd); 

if(!r) return(NULL); 
else return(pd.hDC); 

} 

HANDLE CreateCompatiblelmage(HANDLE source) 

{ 

LPBITMAPINFOHEADER Ipbi; 
int bits,dbits; 

if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(source)) == NULL) 
return(NULL); 

bits=(int)lpbi->biBitCount; 

GlobalUnlock(source); 
dbits=GetDisplayBits(); 

if(dbits >= bits) return(NULL); 
switch (dibits)■. { 

case 8: return(Dither256(source)); 
case 4: return(Ditherl6(source)); 
case 1: return(Dither2(source)); 
default: return(NULL); 

} 

} 

WORD GetDisplayBits() 

{ 
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HDC hdc; 
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Figure 2-4 Continued. 

WORD i; 

hdc=GetDC(NULL); 

i=(WORD)(GetDeviceCaps(hdc,PLANES) * 

GetDeviceCaps(hdc,BITSPIXEL)); 
if (i > 8) i=24; 

ReleaseDC(NULL,hdc); 

return(i); 

} 

WORD HandleDialogScrollMessage(HWND hwnd,WPARAM wParam, 
LPARAM lParam,WORD type) 

{ 

int pos,range,jump; 

pos=GetScrollPos(hwnd,type); 

GetScrollRange(hwnd,type,&jump,Grange); 
jump=range/8; 

switch (LOWORD (wParam) ) { 

case SB_LINEUP: 
pos-=l; 
break; 

case SB_LINEDOWN: 
pos+=l; 
break; 

case SB_PAGEUP: 
pos-=jump; 
break; 

case SB_PAGEDOWN: 
pos+=jump; 
break; 

case SB_THUMBPOSITION: 
case SB_THUMBTRACK: 

#ifdef _WIN32_ 

pos=HIWORD(wParam); 

#else 

pos=LOWORD(IParam); 

#endif 

break; 

} 

if(pos < 0) pos=0; 
else if(pos > range) pos=range; 

if(pos != GetScrollPos(hwnd,type)) { 

SetScrollPos(hwnd,type,pos,TRUE); 
return(TRUE); 

} 

return(FALSE); 

} 
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WORD SetScrollBars(HWND hwnd,HANDLE handle) 

{ 

LPBITMAPINFOHEADER lpbi; 

RECT rect; 

unsigned int width,depth; 

if(handle==NULL) { 

SetScrollPos(hwnd,SB_VERT,0,TRUE); 

SetScrollPos(hwnd,SBJHORZ,0,TRUE); 

SetScrollRange(hwnd,SB_VERT,0,0,FALSE); 
SetScrollRange(hwnd,SB_HORZ,0,0,FALSE); 
return(FALSE); 

} 

if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(handle))== NULL) 
SetScrollPos(hwnd,SB_VERT,0,TRUE); 

SetScrollPos(hwnd,SB_HORZ,0,TRUE); 

SetScrollRange(hwnd,SB_VERT,0,0,FALSE); 
SetScrollRange(hwnd,SB_HORZ,0,0,FALSE); 
return(FALSE); 

} 

GetClientRect(hwnd,&rect); 

width=rect.right-rect.left ; 
depth=rect.bottom-rect.top; 

SetScrollPos(hwnd,SB_VERT,0,TRUE); 

SetScrollPos(hwnd,SB_HORZ,0,TRUE); 

if(width < (unsigned int)lpbi->biWidth) 

SetScrollRange(hwnd,SB_HORZ,0, 

LPBwidth(lpbi)-width,FALSE); 

else 

SetScrollRange(hwnd,SB_HORZ,0,0,FALSE); 

if(depth < (unsigned int)lpbi->biHeight) 

SetScrollRange(hwnd,SB_VERT,0, 

LPBdepth(lpbi)-depth,FALSE); 

else 

SetScrollRange(hwnd,SB_VERT,0,0,FALSE); 

GlobalUnlock(handle); 

return(TRUE); 

} 

WORD DoInfo(HWND hwnd,LPSTR path) 

{ 

HANDLE handle; 

LPBITMAPINFOHEADER lpbi; 
char b[512]; 
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Continued. 

if((handle=GetFileInformation(path)) == NULL) { 
DoMessage(hwnd,"Error getting information, 
return(FALSE); 


} 


) ; 


if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(handle))==NULL) 
DoMessage(hwnd,"Error locking information."); 
return(FALSE); 


} 


{ 


wsprintf(b,"File: %s\n" 

"Dimensions: %u x %u\n" 

"Colours: %lu\n", 

(LPSTR)path, 

LPBwidth(lpbi),LPBdepth(lpbi), 

1L << LPBbits(lpbi)); 

MessageBox(hwnd,b,"File Information",MB_OK); 
GlobalUnlock(handle); 


return(TRUE); 

} 


int GetFileName(HWND hwnd,LPSTR path) 

{ 

OPENFILENAME ofn; 
char szDirName[257],szFile[256] ; 
char szFileTitle[256],szFilter[768],*p; 
int r; 

if(szDirName[lstrlen(szDirName)-1] != '\\') 

Istreat(szDirName,"\\"); 


lstrcpy(szFile, "*."); 

lstrcat(szFile,GetFileExtension()); 

p=szFilter; 

lstrcpy(p,"All files"); 
p+=lstrlen(p)+1; 
lstrcpy(p, "*.*") ; 
p+=lstrlen(p)+l; 

lstrcpy(p,GetFileExtension()); 

lstrcat(p," files"); 

p+=lstrlen(p)+1; 

lstrcpy(p, "* . ") ; 

lstrcat(p,GetFileExtension()); 

p+=lstrlen(p)+1; 

*p=0 ; 

memset((char *)&ofn,0,sizeof(OPENFILENAME)); 
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szFileTitle[0]=0; 

ofn.lStructSize=sizeof(OPENFILENAME); 

ofn.hwndOwner=hwnd; 

ofn.hlnstance=hlnst; 

ofn.lpstrFilter=szFilter; 

ofn.nFilterIndex=2; 

ofn.lpstrFile=szFile; 

ofn.nMaxFile=sizeof(szFile); 

ofn.lpstrFileTitle=szFileTitle; 

ofn.nMaxFileTitle=sizeof(szFileTitle); 

ofn.lpstrInitialDir=szDirName; 

ofn.Flags=OFN_PATHMUSTEXIST ! OFN_FILEMUSTEXIST; 

ofn.lpstrTitle="Open"; 

ofn.nFileExtension=0; 

ofn.IpstrDefExt=NULL; 

r=GetOpenFileName(&ofn); 

Istrcpy(path,ofn.IpstrFile); 

return(r); 


int PutFileName(HWND hwnd,LPSTR path) 

{ 

OPENFILENAME ofn; 
char szDirName[257],szFile[256]; 
char szFileTitle[256],szFilter[768],*p; 
int r ; 

if(szDirName[lstrlen(szDirName)-1] != '\\') 

lstrcat(szDirName,"\\") ; 

Istrcpy(szFile, "*") ; 

lstrcat(szFile,GetFileExtension()); 

szFile[lstrlen(szFile)-1]=0; 

p=szFilter; 

Istrcpy(p,"All files"); 
p+=lstrlen(p)+1; 

Istrcpy(p,"*.*") ; 
p+=lstrlen(p)+1; 

Istrcpy(p,GetFileExtension()); 
lstrcat(p," files"); 
p+=lstrlen(p)+1; 

Istrcpy(p,"*.") ; 

lstrcat(p,GetFileExtension()); 

p+=lstrlen(p)+1; 

*p=0; 

if(lstrlen(path)) Istrcpy(szFile,path); 
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Continued . 

else { 

lstrcpy(szFile,"UNKNOWN."); 
lstrcat(szFile,GetFileExtension()); 

} 

memset((char *)&ofn,0,sizeof(OPENFILENAME)); 
szFileTitle[0]=0; 

ofn.lStructSize=sizeof(OPENFILENAME); 

ofn.hwndOwner=hwnd; 

ofn.hlnstance=hlnst; 

ofn.lpstrFilter=szFilter; 

ofn.nFilterIndex=2; 

ofn.lpstrFile=szFile; 

ofn.nMaxFile=sizeof(szFile); 

ofn.lpstrFileTitle=NULL; 

ofn.nMaxFileTitle=0; 

ofn.lpstrInitialDir=szDirName; 

ofn.Flags=OFN_PATHMUSTEXIST ! OFN_FILEMUSTEXIST 
OFN_OVERWRITEPROMPT; 
ofn.IpstrTitle="Save As"; 
ofn.nFileExtension=l; 
ofn.IpstrDefExt=GetFileExtension(); 
ofn.lpTemplateName=(LPSTR)"FileSave"; 
r=GetSaveFileName(&ofn); 

lstrcpy(path,ofn.IpstrFile); 

return(r); 

} 

void CentreWindow(HWND hwnd) 

{ 

RECT rect; 
unsigned int x,y; 

GetWindowRect(hwnd,&rect); 
x=(GetSystemMetrics(SM_CXSCREEN)- 
(rect.right-rect.left))/2; 
y=(GetSystemMetrics(SM_CYSCREEN)- 
(rect.bottom-rect.top))/2; 

SetWindowPos(hwnd,NULL,x,y,rect.right-rect.left, 
rect.bottom-rect.top,SWP_NOSIZE); 

} 

void DoHelp(HWND hwnd,LPSTR keyword) 

{ 

char b[145]; 

MakeHelpPathName (b) ; 

WinHelp(hwnd,b,HELP_KEY,(DWORD)keyword); 





Displaying bitmapped graphics 


Continued. 

} 

void SetHelpSize(HWND hwnd) 

{ 

HELPWININFO helpinfo; 
char b[145]; 

lmemset ( (LPSTR) Schelpinf o, 0 , sizeof (HELPWININFO) ) ; 

helpinfo.wStructSize=sizeof(HELPWININFO); 

helpinfo.x=10; 

helpinfo.y=10; 

helpinfo.dx=512; 

helpinfo.dy=1004; 

MakeHelpPathName(b); 

WinHelp(hwnd,b,HELP_SETWINPOS / (DWORD) Schelpinfo); 

} 

void MakeHelpPathName(LPSTR szFileName) 

{ 

LPSTR pcFileName; 
int nFileNameLen; 

nFileNameLen = GetModuleFileName(hlnst,szFileName,144); 
pcFileName = szFileName+nFileNameLen; 

while(pcFileName > szFileName) { 

if(*pcFileName == '\\ 1 !! *pcFileName == ':') { 

*(++pcFileName) = '\0'; 
break; 

} 

nFileNameLen--; 
pcFileName--; 

} 

if((nFileNameLen+13) < 144) lstrcat(szFileName,HELPFILE); 
else lstrcat(szFileName, "?"); 

} 

void DoMessage(HWND hwnd,LPSTR message) 

{ 

MessageBox(hwnd,message,"Message", 

MB_OK ! MB_I CONINFORMATI ON) ; 

} 

void DoAbout(HWND hwnd) 

{ 

#ifdef WIN32 

MEMORYSTATUS ms; 

#endif 

long 1; 
char b[512]; 
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#ifdef _WIN32_ 

GlobalCompact(OxffffffffL); 

GlobalMemoryStatus(&ms); 
l=ms.dwAvailPhys; 

#endif 

#ifdef _WIN16_ 

l=GetFreeSpace(0); 

#endif 

wsprintf(b,"%s viewer %u.%u for %s\n\n" 

"Copyright \251 1995 Alchemy Mindworks Inc.\n\n" 
"Contains no polysorbate 80 or tropical oils.\n" 
"Recycle where required by law. Not for use\n" 

"by children or liberals. Not recommended for\n" 
"fuel-injected engines. For more information\n" 
"contact 1-800-CAT-FOOD.\n\n" 

"%lu bytes of free memory.\n\n" 

"%sLIB %u.%u %s\n" 

"DIBLIB %u.%u %s", 

(LPSTR)GetFileExtension(), 

VERSION, 

SUBVERSION, 

(LPSTR)PLATFORM, 

1, 

(LPSTR)GetFileExtension(), 

(unsigned int) ( (GetLibraryVersion() »8) & OxOOff) , 
(unsigned int)(GetLibraryVersion() & OxOOff), 

(LPSTR)GetCopyright(), 

(unsigned int)((GetDibLibraryVersion()»8) & OxOOff), 
(unsigned int)(GetDibLibraryVersion() & OxOOff), 
(LPSTR)GetDibCopyright() 

) ; 

MessageBox(hwnd,b,"Message",MB_OK ! MB_ICONINFORMATION); 

} 

int CreateMainWindow(HANDLE hlnstance, 

HANDLE hPrevInstance,LPSTR IpszCmdParam,int nCmdShow) 

{ 

HBITMAP hBitmap; 

HBRUSH hBrush; 

HCURSOR hSaveCursor,hHourGlass; 

HMENU hmenu; 

HWND hwnd; 

MSG msg; 

WNDCLASS wndclass; 
char b[STRINGSIZE]; 

hBitmap=LoadBitmap(hlnstance,"BackgroundBrush"); 
hBrush=CreatePatternBrush(hBitmap); 







Displaying bitmapped graphics 


Continued. 

if (!hPrevInstance) { 

wndclass.style = CS_HREDRAW ! CS_VREDRAW; 
wndclass.lpfnWndProc=SelectProc; 
wndclass.cbClsExtra=0; 
wndclass.cbWndExtra=0; 
wndclass.hlnstance=hlnstance; 

wndclass.hlcon^Loadlcon(hlnstance,szAppName); 
wndclass.hCursor=LoadCursor(NULL,IDC_ARROW); 
wndclass.hbrBackground= 

(hBrush==NULL ? 

GetStockObject(LTGRAY_BRUSH) : hBrush); 
wndclass.lpszMenuName="MainMenu"; 
wndclass. lpszClassName=szAppName; 

if(!RegisterClass(kwndclass)) { 

DoMessage(NULL, 

"Error registering the application class."); 
return(FALSE); 

} 

} 

hlnst=hlnstance; 

hwnd = CreateWindow(szAppName, 

APPLICATION, 

WS_OVERLAPPED ! WS_CAPTION ! WS_SYSMENU ! 
WS_MAXIMIZEBOX ! WS_MINIMIZEBOX ! 

WS_VSCROLL ! WS_HSCROLL ! WS_THICKFRAME, 
CW_USEDEFAULT,CW_USEDEFAULT, 

CW_USEDEFAULT,CW_USEDEFAULT, 

NULL, 

NULL, 

hlnstance, 

NULL); 

if(hwnd==NULL) { 

DoMessage(NULL, 

"Error creating the application window."); 
return(FALSE); 

} 

CentreWindow(hwnd); 

nextViewer=SetClipboardViewer(hwnd); 
hmenu=GetMenu(hwnd); 

if(IsClipboardFormatAvailable(CF_DIB)) 

EnableMenuItem(hmenu,EDIT_PASTE, 

MF_ENABLED ! MF_BYCOMMAND); 

EnableMenuItem(hmenu,EDIT_PASTE, 

MF_GRAYED ! MF_BYCOMMAND) ; 


Figure 2"4 



else 







Figure 2-4 Continued. 

if(IpszCmdParam != NULL && lpszCmdParam[0]) { 

Wait(); 

if((image=ReadGraphicFile(IpszCmdParam))==NULL) { 
GetError(b); 

DoMessage(hwnd,b); 

} 

InvalidateRect(hwnd,NULL,TRUE); 

SetScrollBars(hwnd,image); 
displayimage=CreateCompatibleImage(image); 

NoWait(); 



SetFileOpen(); 

ShowWindow(hwnd,nCmdShow); 

UpdateWindow(hwnd); 

while(GetMessage(&msg,NULL,0,0)) { 

TranslateMessage(&msg); 

DispatchMessage(&msg); 

} 

UnregisterClass(szAppName,hlnst); 

DeleteObject(hBrush); 

DeleteObject(hBitmap); 

return (msg.wParam) ; 

} 

Actually, CreateMainWindow is the repository for all sorts of 
initialization and Windows dogma. It begins by creating a brush to 
define the background of the client area of the VIEWER window. This 
is, in fact, wholly decorative, although it illustrates yet another use for 
bitmaps. In this case, the bitmap in question is stored in the resource 
file for VIEWER and is named BackgroundBrush. The 
CreatePatternBrush GDI call creates a brush based on its contents, 
which then can be passed to RegisterClass as the hbrBackground 
element of its WINCLASS object. The bitmaps used for background 
brushes are constrained to be of the dimensions 8 by 8, which is a 
really tiny bitmap. You can create some interesting repeating patterns 
with a background bitmap, however. 

The Graphic Workshop for Windows shareware on the companion 
CD-ROM for this book will allow you to view a bitmap tiled, making it 
easier to see what a background brush will look like when it’s used in 
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this context. Open the bitmap in question in the Graphic Workshop 
view mode, and select Tile from the Picture menu. 

The CreateMainWindow function checks its command-line arguments 
once it has its window up and running, and if it finds a path to an 
image file therein, it will load the file and get it ready to be displayed 
in the window that’s about to appear. The process of unpacking and 
displaying an image will be discussed in detail shortly. 

When CreateMainWindow has completed its initialization, it drops 
into a message loop and passes the messages for its window to 
SelectProc. The SelectProc function handles the main window 
messages and is where all the work gets done. 

Because VIEWER uses the Windows clipboard, it must manage the 
clipboard chain and handle WM_DRAWCLIPBOARD and 
WM_CHANGECBCHAIN messages. These messages are sent to all 
the windows open on your desktop whenever something changes on 
the clipboard. The VIEWER application will watch for these messages 
and adjust its menus according to what it finds. Specifically, if there’s 
a device-independent bitmap on the clipboard, it will enable the Paste 
item of the Edit menu. Any other sort of clipboard contents will cause 
the Paste function to be disabled. 

Things start moving in SelectProc when someone selects Open from 
the File menu. The GetFileName function, defined later in 
VIEWER.CPP, uses a call to the Windows common dialog library to 
display a File Open dialog and ask for a filename. Assuming that it 
returns with a valid filename, it uses the Wait macro to display an 
hourglass cursor and calls ReadGraphicFile to fetch the file in 
question. 

The Windows common dialogs are a major topic all by themselves, 
and a fairly complicated one at that. If you’d like to know how to 
really make them get up and dance—as opposed to the quick two-step 
out to the back garden for a crafty smoke illustrated here—you might 
want to check out my book Constructing Windows Dialogs , published 
by McGraw/Hill. It also gets into the details of Help files and using the 
Windows Help system. While the VIEWER application includes Help 
functions, and you’ll find a source RTF Help source file on the 





companion CD-ROM for this book, it’s beyond the scope of this 
chapter to get involved in the murky and ill-defined backwaters of 
Help. 

ReadGraphicFile is the first instance of a call to one of the graphic 
file format DLLs. Each of the libraries includes the following exported 
functions: 

LPSTR GetFileExtension(VOID) —This function returns the file 
extension for the format supported by the DLL. 

WORD GetLibraryVersion(VOID) —This function returns the version 
number of the library, with the major version in the high-order byte of 
the return value and the minor version in the low-order byte of the 
return value. 

FIANDLE GetFilelnformation(LPSTR path) —This function returns a 
handle to a BITMAPINFOFIEADER that defines the file passed to it but 
that includes no bitmap information. If the file cannot be found or 
doesn’t read correctly, the return value will be NULL. The GetError 
function will return more information about the problem. 

FIANDLE ReadGraphicFile(LPSTR path) —This function returns a 
handle to device-independent bitmap that contains the unpacked 
image from the file passed to it. If the file cannot be found or doesn’t 
read correctly, the return value will be NULL. The GetError function 
will return more information about the problem. 

WORD WriteGraphicFile(LPSTR path, FIANDLE bitmap) —This 
function compresses the device-independent bitmap in bitmap into a 
file defined by path. It returns TRUE if it’s successful or FALSE if there 
was an error. The GetError function will return more information 
about the problem. 

WORD GetError(LPSTR text) —This function returns the most recent 
error code, or NO_ERROR if there has been no error since the last 
call to GetFilelnformation, ReadGraphicFile, or WriteGraphicFile. If 
the pointer passed to it is not NULL, it will fill the string it points to 
with a text description of the error. 






LPSTR GetCopyright(VOID) —This function returns the copyright 
string for the current graphic file format library. 

LPSTR GetNotice(VOID) —This function returns the notice string for 
the current graphic file format library. 

Prototypes and related constants—such as the library error codes—are 
defined in the WINBIT.H file. 

Allowing that ReadGraphicFile returns a valid handle to a device¬ 
independent bitmap, the viewer will set itself up to display its 
contents. The call to InvalidateRect causes the client area of the 
viewer window to be marked as invalid; that is, in need up updating. A 
WM_PAINT message is placed in the message queue. The 
SetScrollBars function, defined further down in VIEWER.CPP, adjusts 
the scroll bars based on the relative dimensions of the VIEWER 
window and the image dimensions. It will disable the scroll bars if the 
image is smaller than the VIEWER window. 

The SetFileOpen call is actually a macro defined at the top of 
VIEWER.CPP. It enables and disables several menu items in the 
VIEWER window based on the state of image, the handle that was 
returned by ReadGraphicFile. For example, once a file is open, the 
Print item in the Edit menu will have something to work with, and as 
such can be enabled. 

The CreateCompatiblelmage function deals with one of the principal 
problems of displaying bitmaps of unrestricted color depth under 
Windows. If you attempt to display an image with more color depth 
than your current screen Windows driver can handle, Windows will 
remap it, as discussed earlier in this chapter. The 
CreateCompatibielmage function sees to it that this never happens. 

It can reduce the number of colors in an image less destructively than 
Windows can. You can see the declaration for this function shortly 
after the end of SelectProc in VIEWER.CPP. 

The CreateCompatiblelmage function begins by locking the handle 
of the device-independent bitmap passed to it to ascertain its color 
depth. It then calls GetDisplayBits to ascertain the color depth of the 
current Windows display driver. You’ll find GetDisplayBits defined 








immediately after CreateCompatiblelmage. Note that it will return 24 
bits even if your screen driver only supports 15 or 16 bits of color. For 
the purposes of this book there are no 15- or 16-bit device¬ 
independent bitmaps. 

If the color depth of the image in question is no greater than that of 
your current Windows screen driver, CreateCompatiblelmage will do 
nothing, and its return value will be NULL. Should 
CreateCompatiblelmage decide that it has to lose some color depth, 
it will call one of three dithering functions. These will be discussed in 
greater detail later in this chapter. It will return a handle to a new 
bitmap, and VIEWER will subsequently maintain two copies of its 
bitmap in memory: the original one returned by ReadGraphicFile for 
printing or writing out to a new file and a dithered one for displaying. 

Once a file has been opened and loaded, SelectProc returns to its 
calling function—essentially to the message loop in 
CreateMainWindow —until the WM_PAINT message posted by 
InvalidateRect turns up. It’s handled by SelectProc as well. The 
WM_PAINT handler will call ShowDIB to paint the contents of 
displayimage in the client area of the VIEWER window, if 
displayimage isn’t NULL, or the contents of image, if it is. It uses 
GetScrollPos to determine the offset from the upper-left corner of the 
source rectangle of the bitmap represented by the current scroll bar 
positions. 

I should note that the dithering functions mentioned a few paragraphs 
earlier and the ShowDIB function encountered in the WM_PAINT 
handler of SelectProc don’t reside in VIEWER.CPP. They’re part of 
another dynamic link library, DIBLIB.DLL, to be dealt with later in this 
chapter. 

Once VIEWER has painted the contents of its main window, you can 
scroll over the displayed image with the scroll bars. Moving a scroll bar 
causes SelectProc to receive a WM_VSCROLL or WM_HSCROLL 
message. It responds to these by calling the 

HandleDialogScrollMessage and then invalidating the client area of 
the VIEWER window, causing it to be repainted with a new section of 
the bitmap to be displayed. 
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The HandleDialogScrollMessage function, declared about half way 
down VIEWER.CPP, takes care of requests to update the position of a 
scroll bar. Windows doesn’t automatically update the thumb position 
of a scroll bar—it just tells the message handler of the window it’s 
associated with that something has changed. 

There’s a really nasty little secret buried in 

HandleDialogScrollMessage. Under 16-bit Windows, the current 
scroll position is returned in the low-order word of the IParam 
argument for a scroll bar message. Under 32-bit Windows, it has 
moved to the high-order word of wParam. If you don’t keep track of 
this, you’ll probably stomp your cat into a stain in raging frustration 
trying to figure out why scroll bars don’t track properly in 32-bit 
Windows applications. This is probably no great loss—cats were 
provided to keep your Reeboks from getting damaged by hard floors— 
but it is easily avoided if you know about it. 

Note that WM_SIZE messages are also handled in SelectProc by 
invalidating the client window area. When the client window gets 
resized, it must be repainted to allow for the possibility that it has 
gotten larger. The scroll bars must also be readjusted. 

Windows purists—or perhaps Windows puritans—will note that, when 
the client area of VIEWER’S window is resized, it’s not necessary to 
repaint the whole bitmap, but rather just those portions that are 
affected by resizing. To be sure, the approach I’ve taken here has 
been designed to be easy to understand, rather than as frugal as 
possible with Windows’ resources. Once you get the viewers discussed 
in this book working and obedient, you might want to look at the 
possibility of rewriting the WM_PAINT handler in SelectProc to do 
more efficient updates. 

The FILE_CLOSE command handler in SelectProc takes care of 
disposing of any objects that were created by the FILE_OPEN case— 
in this case, the image and displayimage bitmaps. It disables the 
VIEWER scroll bars and invalidates its client area so that it will be 
repainted with the background pattern. 

The FILE_SAVEAS handler in SelectProc calls WriteGraphicFile from 
the current graphic file format library—very much the FILE_OPEN 
case in reverse. 







The FILE_NOTICE handler calls GetNotice from the current file 
format library and displays whatever it says. In some cases, the notices 
include copyright information about third-party libraries that have been 
used in the format-specific DLLs. There is also one legal warning, to 
be dealt with in detail in the next chapter of this book. 

The HELP_ABOUT handler also displays a canned message, making 
calls into DIBLIB.DLL and the current graphic file format library for 
version numbers and copyright information. To the best of my 
knowledge, 1-800-CAT-FOOD is not a working phone number. There 
are a number of additional cases in the WM_COMMAND handler for 
SelectProc, but you’ll find that they all make calls to functions that 
don’t exist in VIEWER.CPP. These are functions that are provided by 
DIBLIB.DLL, to be dealt with next. 

Pay particular attention to the EDIT_PASTE handler. This is a very 
simple sort of paste function, in that it just replaces the existing image 
with the bitmap on the clipboard. It actually does pretty much what 
FILE_OPEN did, except that it fetches its bitmap from the clipboard, 
rather from a file. 

If you bought this book to incorporate bitmapped graphic functions 
into your software, it’s worth noting that VIEWER.CPP is the only 
source code you actually need get up close and personal with. You can 
use all the other functions in this book by copying the appropriate 
DLLs from the companion CD-ROM and linking them to your 
software. Source code for the libraries is provided only for the 
adventurous. 

The dirty little secrets of 
DIBLIB.DLL: 

Whitewater for software 

There are a number of functions called by VIEWER that you might find 
useful in your own software—which is why they live in a separate, 
easily portable library. 
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The source code for DIBLIB is illustrated in Fig. 2-5. Among other 
things, this is the first DLL to turn up in this book. Note that, while 
the functional aspects of DIBLIB.CPP are portable between 16- and 
32-bit environments, the DLL entry and exit code changes. A 16-bit 
DLL requires LibMain and WEP functions, while a 32-bit DLL has 
DIIEntryPoint and no exit code. 

/* Figure 2-5 

Bitmap Library 

Copyright (c) 1995 Alchemy Mindworks Inc. 


*/ 

#include <windows.h> 

#include <stdio.h> 

#include <string.h> 

#include <stdlib.h> 

#include "winbit.h" 

HANDLE hlnst; 

#ifdef WIN32 

#pragma argsused 

DLL_EXPORT (BOOL) DIIEntryPoint(HINSTANCE hlnstance, 
DWORD wDataSeg,LPVOID lpCmdLine) 

{ 

hlnst=hlnstance; 
return(TRUE); 

} 

#endif 

#ifdef _WIN16_ 

#pragma argsused 

DLL_EXPORT (int) LibMain(HANDLE hlnstance, 

WORD wDataSeg,WORD wHeapSize, LPSTR lpCmdLine) 

{ 

hlnst=hlnstance; 

if (wHeapSize > 0) UnlockData(0) ; 
return(TRUE); 

} 

#pragma argsused 

DLLJEXPORT (int) WEP(int nParameter) 

{ 

return (TRUE); 



The DIBLIB. CPP source code. 
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#endif 

DLL_EXPORT(WORD) ShowDib(HDC hdc,HANDLE handle,WORD x,WORD y) 

{ 

LPBITMAPINFOHEADER lpbi; 

LPBITMAPINFO lpbp; 

LPLOGPALETTE pLogPal=NULL; 

HANDLE hPal=NULL,oldPal=NULL; 

HPSTR p; 
unsigned int i; 

if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(handle)) != NULL) { 

lpbp=(LPBITMAPINFO)lpbi; 
if(LPBbits(lpbi) <= 8) { 

if((pLogPal=(LPLOGPALETTE) 

FixedGlobalAlloc(sizeof(LOGPALETTE)+ 

((unsigned int)lpbi->biClrUsed* 

sizeof(PALETTEENTRY)))) == NULL) { 
GlobalUnlock(handle); 
return(FALSE); 

} 

pLogPal->palVersion=0x03 00 ; 
pLogPal->palNumEntries=LPBcolours(lpbi); 

for (i=0;i<pLogPal->palNumEntries;++i) { 
pLogPal->palPalEntry[i].peRed= 
lpbp->bmiColors[i].rgbRed; 
pLogPal->palPalEntry[i].peGreen= 
lpbp->bmiColors[i].rgbGreen; 
pLogPal->palPalEntry[i].peBlue= 
lpbp->bmiColors[i].rgbBlue; 
pLogPal->palPalEntry[i].peFlags=0; 

} 

hPal=CreatePalette(pLogPal); 

oldPal=SelectPalette(hdc,hPal,0); 

RealizePalette(hdc); 

FixedGlobalFree(pLogPal); 

} 

p=LPBimage(lpbi); 

SetDIBitsToDevice(hdc, 

0, 

0, 

LPBwidth(lpbi) , 

LPBdepth(lpbi), 
x, 

-Y/ 
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o, 

LPBdepth(lpbi), 
p ' 

(LPBITMAPINFO)lpbi, 

DIB_RGB_COLORS); 

if(oldPal != NULL) SelectObject(hdc,oldPal); 

if(hPal != NULL) DeleteObject(hPal); 

GlobalUnlock(handle); 

return(TRUE); 

} i 

return(FALSE); 

} | 

DLL_EXPORT (WORD) PrintBitmap(HDC hpr,HANDLE handle) 

{ 

LPBITMAPINFOHEADER lpbi; 

WORD r; 

unsigned int width,depth; 

if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(handle)) ==NULL) 
return(FALSE); 

width=(unsigned int)lpbi->biWidth; 
depth=(unsigned int)lpbi->biHeight; 

GlobalUnlock(handle); 

Escape(hpr,STARTDOC,8,"Document",NULL); 

r=DibBlt(hpr,20,20,width,depth,handle,0,0); 

if(Escape(hpr,NEWFRAME,0,NULL,NULL) >0) 

Escape(hpr,ENDDOC,0,NULL,NULL); 

return(r); 

} j 

void DiffuseFloyd(HPSTR linel,HPSTR line2,int x,int y,int r, 
int g,int b,int mr,int mg,int mb,int width,int depth) 

{ 

int dr.dg.db/Xpos^^vg/Vb; 

dr=(r-mr)»4; 
dg= (g-mg) »4 ; 
db=(b-mb)>>4; 


vr=dr<<l; 

vg=dg<<l; 
vb=db<<l; 
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if((x+l) < width && (y+1) < depth) { 
xpos=RGB_SIZE*(x+1); 

line2[xpos+WRGB_RED] =addb (line2[xpos+WRGB_RED] ,dr) ; 
line2[xpos+WRGB_GREEN]=addb(line2[xpos+WRGB_GREEN],dg); 
line2[xpos+WRGB_BLUE] =addb(line2[xpos+WRGB_BLUE],db); 

} 

dr+=vr; dg+=vg; db+=vb; 

if((x-l) > 0 && (y+1) < depth) { 
xpos=RGB_SIZE*(x-1); 

line2[xpos+WRGB_RED] =addb(line2[xpos+WRGB_RED],dr); 
line2[xpo s +WRGB_GREEN]=addb(line2[xpos+WRGB_GREEN], dg) ; 
line2[xpos+WRGB_BLUE] =addb(line2[xpos+WRGB_BLUE],db); 

} 

dr+=vr; dg+=vg; db+=vb; 

if((y+1) < depth) { 

xpos=RGB_SIZE*(x); 

line2[xpos+WRGB_RED] =addb(line2[xpos+WRGB_RED],dr); 
line2[xpos +WRGB_GREEN]=addb(line2[xpo s +WRGB_GREEN] ,dg) ; 
line2[xpos+WRGB_BLUE] =addb(line2[xpos+WRGB_BLUE],db); 

i > 

dr+=vr; dg+=vg; db+=vb; 

if((x+1) < width) { 

xpos=RGB_SIZE*(x+1); 

linel[xpos +WRGB_RED] =addb(linel[xpos+WRGB_RED ], dr); 
linel[xpos +WRGB_GREEN]=addb(linel[xpos +WRGB_GREEN],dg); 
linel[xpos+WRGB_BLUE] =addb(linel[xpos+WRGB_BLUE],db); 

} 

} 

#define DestroyAllObjects(success) (\ 

if(hsource != NULL && lpbs != NULL) GlobalUnlock(hsource);\ 
if(hdest != NULL && lpbd != NULL) GlobalUnlock(hdest);\ 
if(hdest != NULL && Isuccess) GlobalFree(hdest);\ 

} 

HANDLE Duplicatelmage(HANDLE hsource) 

{ 

HANDLE hdest=NULL; 

LPBITMAPINFOHEADER lpbs=NULL,lpbd=NULL; 

HPSTR ps,pd; 
char palette[768]; 
unsigned int i; 

if((lpbs=(LPBITMAPINFOHEADER)GlobalLock(hsource))==NULL) { 
DestroyAllObjects(FALSE); 
return(NULL); 



} 
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Continued. 

GetDibPalette((LPBITMAPINFO)lpbs,palette); 

if((hdest=CreateDib(LPBwidth(lpbs),LPBdepth(lpbs), 
palette,LPBbits(lpbs)))==NULL) { 

DestroyAllObjects(FALSE); 
return(NULL); 

} 

if((lpbd=(LPBITMAPINFOHEADER)GlobalLock(hdest))==NULL) { 
DestroyAllObjects(NULL); 
return(NULL); 

} 

ps=LPBimage(lpbs); 
pd=LPBimage(Ipbd); 

for(i=0;i<LPBdepth(lpbs);++i) { 

hmemcpy(pd,ps,LPBlinewidth(lpbs)); 

ps+=(long)LPBlinewidth(lpbs); 
pd+=(long)LPBlinewidth(lpbs); 

} 

DestroyAllObjects(TRUE); 
return(hdest); 

} 

#undef DestroyAllObjects() 

#define DestroyAllObjects(success) {\ 

if(hsource != NULL && lpbs != NULL) GlobalUnlock(hsource);\ 
if(hsource != NULL && lpbd != NULL) GlobalFree(hsource);\ 
if(hdest != NULL && lpbd != NULL) GlobalUnlock(hdest);\ 
if(hdest != NULL && (success) GlobalFree(hdest);\ 

} 

DLL_EXPORT (HANDLE) Dither256(HANDLE hsource) 

{ 

HANDLE hdest=NULL; 

LPBITMAPINFOHEADER lpbs=NULL,lpbd=NULL; 

LPSTR pr; 

HPSTR source=NULL,dest=NULL; 
char palette[768]; 
unsigned int k,r,g,b,mr,mg,mb; 
unsigned int i,j; 

if((lpbs=(LPBITMAPINFOHEADER)GlobalLock(hsource))==NULL) 
return(NULL); 

GlobalUnlock(hsource); 
lpbs=NULL; 

if((hsource=DuplicateImage(hsource))—NULL) return(NULL); 


Figure 2-5 
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if((lpbs=(LPBITMAPINFOHEADER)GlobalLock(hsource))==NULL) { 
DestroyAllObjects(FALSE); 
return(NULL); 

} 

GetOrthoPalette(palette); 

if((hdest=CreateDib(LPBwidth(lpbs), 

LPBdepth(lpbs),palette,8))==NULL) { 

DestroyAllObjects(FALSE); 
return(NULL); 

} 

if((lpbd=(LPBITMAPINFOHEADER)GlobalLock(hdest))==NULL) { 
DestroyAllObjects(FALSE); 
return(NULL); 

} 

source=LPBimage(lpbs); 
dest=LPBimage(lpbd); 

for(i=0;i<LPBdepth(lpbs);++i) { 

for(j=0;j<LPBwidth(lpbs);++j) { 

k=RGB_SIZE*j; 
r=source[k+WRGB_RED]; 
g=source[k+WRGB_GREEN]; 
b=s ourc e[k+WRGB_BLUE]; 

k=ORTHOMATCH(r,g,b); 
pr=palette+RGB_SIZE*k; 

dest[j]=k; 
mr=pr[RGB_RED]; 
mg=pr[RGB_GREEN]; 
mb=pr[RGB_BLUE]; 

DiffuseFloyd(source, 

source+(long)LPB1inewidth(lpbs), 

j , 
i / 

r, 

g, 

b, 

mr, 

mg, 

mb, 

LPBwidth(lpbs), 

LPBdepth(lpbs)); 



source+=(long)LPBlinewidth(lpbs); 
dest+=(long)LPBlinewidth(lpbd); 
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Continued. 

} 

DestroyAllObjects(TRUE); 
return(hdest); 

} 

#undef DestroyAllObjects() 

#define DestroyAllObjects(success) {\ 

if(hsource != NULL && lpbs != NULL) GlobalUnlock(hsource);\ 
if(hdest != NULL && lpbd != NULL) GlobalUnlock(hdest);\ 
if(hdest != NULL && !success) GlobalFree(hdest);\ 

} 

DLL_EXPORT (HANDLE) Ditherl6(HANDLE hsource) 

{ 

static char fixedpalette[]={ 

0 , 0 , 0 , 

255, 0, 0, 

0,255, 0, 

255,255, 0, 

0, 0,255, 

255, 0,255, 

0,255,255, 

255,255,255 
}; 


HANDLE hdest=NULL; 

LPBITMAPINFOHEADER lpbs=NULL,lpbd=NULL; 

LPSTR pi; 

HPSTR ps,pd,pr; 
char palette[768]; 
unsigned int ditherlinewidth; 
unsigned int i,j,m,n; 
int r,g,b,bits; 

if((lpbs=(LPBITMAPINFOHEADER)GlobalLock(hsource))==NULL) { 
DestroyAllObjects(FALSE); 
return(NULL); 

} 

bits=(int)LPBbits(lpbs); 

GetDibPalette((LPBITMAPINFO)lpbs,palette); 

if((hdest=CreateDib((WORD)LPBwidth(lpbs),LPBdepth(lpbs), 
fixedpalette, 4) ) —NULL) { 

DestroyAllObjects(FALSE); 
return(NULL); 

} 


Figure 2-5 



ditherlinewidth=PIXELS2BYTES(LPBwidth(lpbs))«2; 
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Continued. 

if(ditherlinewidth & 0x0003) 

ditherlinewidth=(ditherlinewidth ! 3)+1; 


if((lpbd=(LPBITMAPINFOHEADER)GlobalLock(hdest))==NULL) { 
DestroyAllObjects(FALSE); 
return(NULL); 

} 


ps=LPBimage(lpbs); 
pd=LPBimage(lpbd); 

for(i=0;i<LPBdepth(lpbs);++i) { 

pr=ps; 

ps+=LPBlinewidth(lpbs); 


if(bits > 8) { 

for(j=0;j<LPBwidth(lpbs);++j) { 

r=pr[WRGB_RED]; 
g=pr[WRGB_GREEN]; 
b=pr[WRGB_BLUE]; 

m=(bayerPattern[j & 0x0007][i & 0x0007]<<2); 
n=0 ; 

if(r > m) n I= 0x01; 
if(g > m) n != 0x02; 
if(b > m) n != 0x04; 

pr+=RGB_SIZE; 

PutChunkyPixel(pd,j,n); 

} 

} 

else { 

for(j=0;j<LPBwidth(lpbs);++j) { 

pl=palette+*pr++*RGB_SIZE; 
r=pl[RGB_RED]; 
g=pl[RGB_GREEN]; 
b=pl[RGB_BLUE]; 

m= (bayerPattern[j & 0x0007] [i & 0x0007]«2); 
n=0 ; 


} 


if(r > m) n 
if(g > m) n 
if(b > m) n 


0x01; 
0x02; 
0x04; 


PutChunkyPixel(pd,j,n); 
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Continued. 

pd+=LPBlinewidth(lpbd); 

} 

DestroyAllObjects(TRUE); 
return(hdest); 

} 

#undef DestroyAllObj ects() 

#define DestroyAllObjects(success) { \ 

if(hsource != NULL && lpbs != NULL) GlobalUnlock(hsource);\ 
if(source != NULL && Isuccess) GlobalFree(hsource);\ 
if(hdest != NULL && lpbd != NULL) GlobalUnlock(hdest);\ 
if(hdest != NULL && Isuccess) GlobalFree(hdest);\ 

} 

DLL_EXPORT (HANDLE) Dither2(HANDLE hsource) 

{ 

HANDLE hdest=NULL; 

LPBITMAPINFOHEADER lpbs=NULL,lpbd=NULL; 

HPSTR source=NULL,dest=NULL,pss; 
double a,fac; 

char palette[768],greylevel[256]; 
char remap[256]; 
unsigned int i,j,n; 
int bits; 

if((lpbs=(LPBITMAPINFOHEADER)GlobalLock(hsource))==NULL) { 
DestroyAllObjects(FALSE); 
return(NULL); 

} 

bits=(int)LPBbits(lpbs); 

GetMonoPalette(palette); 

if((hdest=CreateDib((WORD)LPBwidth(lpbs),(WORD)LPBdepth(lpbs), 
palette,1))==NULL) { 

DestroyAllObjects(FALSE); 
return(NULL); 

} 

if((lpbd=(LPBITMAPINFOHEADER)GlobalLock(hdest))==NULL) { 
DestroyAllObjects(FALSE); 
return(NULL); 

} 

source=LPBimage(lpbs); 
dest=LPBimage(lpbd); 

GetDibPalette((LPBITMAPINFO)lpbs,palette); 
for(i=0;i<256;++i) 
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Continued. 

greylevel[i]=GREYVALUE(palette[i*RGB_SIZE+RGB_RED], 

palette[i*RGB_SIZE+RGB_GREEN], 
palette[i*RGB_SIZE+RGB_BLUE]); 

fac=256/(256-((double)DITHERCONTRAST*2)); 
a=(double)DITHERBRIGHTNESS-(double)DITHERCONTRAST; 

for(i=0;i<256;++i) { 

if(a > 254) n=254; 
else if(a < 1) n=l; 
else n=(unsigned int)a; 
remap [i] =n; 
a+=fac; 

} 

for(i=0;i<LPBdepth(lpbs);++i) { 

for(j=0;j<LPBwidth(lpbs);++j) { 

if(bits==24) { 

pss=source+(long)j*RGB_SIZE; 
n=GREYVALUE(pss[WRGB_RED], 

pss[WRGB_GREEN], 
pss[RGBJBLUE]); 

} 

else if(bits==8) n=greylevel[source[j]]; 
else n=greylevel[GetChunkyPixel(source,j)]; 

if ( (n=remap [n] »2) > 

bayerPattern[i & 0x0007][j & 0x0007]) 
dest[j»3] != masktable[j & 0x0007]; 

else 

dest[j>>3] &= ~masktable[j & 0x0007]; 

} 

source+=LPBlinewidth(lpbs); 
dest+=LPBlinewidth(lpbd); 

} 

DestroyAl10bjects(TRUE); 
return(hdest); 

} 

#undef DestroyAllObjects(); 

DLL_EXPORT (WORD) GetDibLibraryVersion() 

{ 

return((VERSION « 8) ! SUBVERSION); 

} 

DLL_EXPORT (LPSTR) GetDibCopyright() 

{ 

return((LPSTR)"Copyright \251 1995 Alchemy Mindworks Inc."); 
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Continued. 

} 

#define DestroyAllObjects() { \ 

if(hdest != NULL && lpbd != NULL) GlobalUnlock(hdest);\ 
if(hsource ! = NULL && lpbs ! = NULL) GlobalUnlock(hsource);\ 
if(hdest != NULL) GlobalFree(hdest);\ 

} 

DLL_EXPORT (WORD) CopyPictureToClipboard(HWND hwnd,HANDLE hsource) 

{ 

HPALETTE hpal; 

LPLOGPALETTE lpal; 

LPBITMAPINFOHEADER lpbs=NULL,lpbd=NULL; 

HANDLE hdest=NULL; 

LPSTR ps; 

char palette[768] ; 
int i, j ; 

if((lpbs=(LPBITMAPINFOHEADER)GlobalLock(hsource))==NULL) { 
DestroyAllObjects(); 
return(FALSE); 

} 

GetDibPalette((LPBITMAPINFO)lpbs,palette); 

if((hdest=CreateDib(LPBwidth(lpbs),LPBdepth(lpbs), 
palette,LPBbits(lpbs)))==NULL) { 

DestroyAllObjects() ; 
return(FALSE); 

} 

if((lpbd=(LPBITMAPINFOHEADER)GlobalLock(hdest))==NULL) { 
DestroyAllObjects() ; 
return(FALSE); 

} 

hmemcpy((HPSTR)lpbd,(HPSTR)lpbs, 

(DWORD)sizeof(BITMAPINFOHEADER)+ 

(DWORD)LPBcolours(lpbs)*(DWORD)sizeof(RGBQUAD)+ 
lpbs->biSizeImage); 

GlobalUnlock(hdest); 
lpbd=NULL; 

if(LPBbits(lpbs)==24) j=256; 
else j=l«LPBbits (lpbs) ; 

if((lpal=(LPLOGPALETTE)FixedGlobalAlloc(sizeof(PALETTEENTRY)* 
j+sizeof(LOGPALETTE)))==NULL) { 

DestroyAllObjects(); 
return(FALSE); 
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} 
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lpal->palVersion=0x0300; 
lpal->palNumEntries=j; 

if(LPBbits(lpbs)==24) GetOrthoPalette(palette); 
ps=palette; 


for(i=0;i<j;++i) { 

lpal->palPalEntry[i].peRed=*ps++; 
lpal->palPalEntry[i].peGreen=*ps++; 
lpal->palPalEntry[i].peBlue=*ps++; 
lpal->palPalEntry[i].peFlags=NULL; 

} 

if((hpal=CreatePalette(lpal))==NULL) { 
DestroyAllObjects(); 
return(FALSE); 

} 



FixedGlobalFree(lpal); 

OpenClipboard(hwnd); 

EmptyClipboard(); 

SetClipboardData(CF_DIB,hdest); 

S e tC1ipboardData(CF_PALETTE,hpa1); 

CloseClipboard(); 

hdest=NULL; 

DestroyAllObjects(); 

return(TRUE); 

} 

#undef DestroyAllObjects() 

#define DestroyAllObjects() { \ 

if(hsource != NULL && lpbs != NULL) GlobalUnlock(hsource);\ 
if(hdest != NULL && lpbd != NULL) {\ 

GlobalUnlock(hdest);\ 

GlobalFree(hdest) ;\ 

}\ 

CloseClipboard();\ 

} 

DLL_EXPORT (HANDLE) PastePictureFromClipboard(HWND hwnd) 

{ 

HANDLE hsource=NULL / hdest=NULL; 

LPBITMAPINFOHEADER lpbs=NULL,lpbd=NULL; 
char palette[768]; 

if(IsClipboardFormatAvailable(CF_DIB)) { 

OpenClipboard(hwnd); 

if((hsource=GetClipboardData(CF_DIB)) == NULL) { 
DestroyAllObjects(); 
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return(NULL); 


Figure 


} 

if((lpbs= 

(LPBITMAPINFOHEADER)GlobalLock(hsource)) =m NULL) { 
DestroyAllObjects(); 
return(NULL); 

} 

if((hdest=CreateDib(LPBwidth(lpbs),LPBdepth(lpbs), 
palette,LPBbits(lpbs)))==NULL) { 

DestroyAllObjects(); 
return (NULL) ; 

} 

if((lpbd=(LPBITMAPINFOHEADER)GlobalLock(hdest))==NULL) { 
DestroyAllObjects(); 
return(NULL); 

} 

hmemcpy((HPSTR)lpbd,(HPSTR)lpbs, 

(DWORD)sizeof(BITMAPINFOHEADER)+ 

(DWORD)LPBcolours(lpbs)*(DWORD)sizeof(RGBQUAD)+ 
lpbs->biSizeImage); 

GlobalUnlock(hdest); 

lpbd=NULL; 

DestroyAllObjects() ; 

return(hdest); 

} 

return(NULL); 

} 

#undef DestroyAllObjects() 


This will be a feature of each of the Windows dynamic link libraries in 
this book. 

Exportable functions from a DLL are declared as such with the 
DLL_EXPORT macro, as defined in WINBIT.H. This, too, changes 
slightly between 16- and 32-bit libraries. Here’s what it looks like for a 
32-bit DLL: 

#define DLL_EXPORT extern "C" WINAPI_export 





This is the 16-bit version of DLL_EXPORT—it allows for older 
compilers: 

#define DLL_EXPORT extern "C" FAR PASCAL_export 

Note that, if you decide to use the source code in this book with a 
compiler other than Borland C++, you might have to change the 
definition of DLL_EXPORT. Many compilers don’t want to see the 
_export declaration. 

The DIBLIB library provides a number of functions to the VIEWER 
application. Here’s what they look like: 

WORD GetDibLibraryVersion(VOID) —This function returns the 
version number of the library, with the major version in the high-order 
byte of the return value and the minor version in the low-order byte of 
the return value. 

LPSTR GetDibCopyright(VOID) —This function returns the copyright 
string for the library. 

WORD CopyPictureToClipboard(HWND hwnd,HANDLE hsource)— 
This function will delete the current clipboard contents and copy the 
device-independent bitmap referenced by hsource to the clipboard. 

HANDLE PastePictureFromClipboard(HWND hwnd)— This function 
will return a handle to a device-independent bitmap that contains a 
copy of the current clipboard contents—assuming that the clipboard 
contains a bitmap. 

WORD PrintBitmap(HDC hpr,HANDLE handle) —This function will 
print the bitmap referenced by handle to the printer referenced by 
hpr. 

HANDLE Dither256(HANDLE hsource) —This function will dither a 
24-bit image down to 256 colors. 

HANDLE Dither 1 6(HANDLE hsource) —This function will dither an 8- 
or 24-bit image down to 16 colors. 











HANDLE Dither2(HANDLE hsource) —This function will dither a 4-, 
8-, or 24-bit image down to two colors. 

WORD ShowDIB(HDC hdc,HANDLE handle,WORD x.WORD y)— 
This function will paint the device-independent bitmap referenced by 
handle on the device context referenced by hdc. The x and y 
arguments define the upper-left corner of the source rectangle. 

Several of these functions probably call for a bit more of an 
explanation. A few of the explanations will themselves call for 
explanations—that’s the way software works. The Windows clipboard 
functions are arguably the most complex—let’s deal with them first. 

The Windows clipboard is another example of a resource that is 
shared between multiple applications, although in this case that’s 
more or less the idea. Anything placed on the clipboard should be 
accessible by other applications. In fact, there’s a major catch to 
this—said other applications must be able to deal with data in the 
format that appears on the clipboard. 

A simple example of this can be seen if you place a device¬ 
independent bitmap on the clipboard and then open the Windows 
Notepad application. Notepad deals exclusively with text and has no 
idea what to make of pictures. As such, it would disable its Paste 
menu in this case and refuse to paste the contents of the clipboard 
into a document. 

A Windows application that uses the clipboard is responsible for 
responding to WM_DRAWCLIPBOARD and WM_CHANGECBCHAIN 
messages, as was illustrated earlier in this chapter, such that, when the 
clipboard contents changes, it can set its Edit menu accordingly. 

The clipboard stores things as global memory buffers, typically 
allocated with the Global Alloc function. Buffers intended for use with 
the Windows clipboard should be allocated with the GMEM_SHARE 
flag set, such that their handles become portable between applications. 

Once you pass a handle to the clipboard, it becomes the property of 
Windows, and your application can have nothing more to do with it. 

As such, to copy a bitmap to the clipboard, VIEWER must actually 









duplicate it and pass the duplicated bitmap to the clipboard, while 
hanging onto the original for further screen updates or other uses. 

You can see how this works in the CopyPictureToClipboard function 
in DIBLIB.CPP. The CreateDIB call is used to create a new device¬ 
independent bitmap with the same dimensions and color depth as that 
of the source bitmap. Because the amount of image data will be the 
same in both bitmaps, the hmemcpy function can be used to copy all 
the data to the new bitmap at once—this is memcpy that has been 
modified to work with huge pointers in a 16-bit environment. It 
evaluates out to memcpy in a 32-bit environment. 

By convention, you should put two objects on the clipboard if you 
paste a bitmap to it—these being a handle to the device-independent 
bitmap itself and a handle to a Windows palette that defines the color 
palette of the bitmap. In fact, applications wanting to do something 
with a device-independent bitmap on the clipboard can ascertain what 
its palette should be by looking at the bitmap itself. Sadly, not all of 
them do. The CopyPictureToClipboard function creates an HPAL 
object as well as a new bitmap. 

Putting objects on the clipboard is actually pretty effortless once the 
objects have been correctly prepared. The OpenClipboard API call 
gets the clipboard ready for action. You should always call 
EmptyClipboard to delete any existing objects on it. The 
SetClipboardData function actually passes the handles to the new 
clipboard data to the clipboard manager. Finally, calling 
CloseClipboard puts the clipboard back to sleep. 

Note that the first argument to SetClipboardData is a constant to tell 
the clipboard what sort of data is represented by the handle that’s 
been passed to it. It’s important that this accurately reflect the real 
nature of what a handle refers to when you send it to the clipboard— 
the clipboard is a mindless, trusting soul, and it will believe whatever 
it’s told. Most Windows applications will expect to be passed handles 
that refer to what the clipboard says they refer to and will do fairly 
little sanity checking. 

As an aside, the CopyPictureToClipboard function, like many of the 
functions in the DIBLIB.CPP library, uses a temporary macro called 
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DestroyAIIObjects that is defined just before the function declaration, 
then undefined immediately thereafter. While a bit of a programmer’s 
sloth—and technically not necessary—using these object-destroyer 
macros is a good habit to get into if you write functions that allocate 
buffers, create handles, or otherwise do things that should be undone 
before the function terminates. 

In a complex function like CopyPictureToClipboard, several objects 
are created or locked—in this case, there’s a new device-independent 
bitmap and several locked buffers. There are several places throughout 
the function wherein CopyPictureToClipboard can return prematurely 
because of an error condition, at which time all the objects that have 
been created or locked must be unlocked or destroyed. If you handle 
this explicitly for each case, it’s really easy to miss one. This can lead 
to some really weird software bugs, especially in really complex 
applications. 

To this end, all the possible instances of things being unlocked, 
deleted, or freed up can be put in DestroyAIIObjects, and this macro 
can be called at any place where the function might return. If you 
modify the function, just add more lines to DestroyAIIObjects, and 
they’ll take care of all the locations wherein the function might return. 

The PastePictureFromClipboard works pretty much like 
CopyPictureToClipboard in reverse. Note that it calls 
IsClipboardFormatAvailable to make sure that there’s really a device¬ 
independent bitmap on the clipboard. It uses GetClipboardData to 
fetch a handle to the bitmap to be pasted. 

The handle returned by GetClipboardData remains the property of 
the clipboard. You can lock it down and copy its contents, but when 
PastePictureFromClipboard returns, it must be unlocked and its 
contents unmodified. As such, most of the work of this function is to 
create a duplicate of the bitmap pointed to by this handle and copy 
the device-independent bitmap from the clipboard into it. 

The other function that’s fairly important to VIEWER is ShowDIB, 
which it calls to update its window with the bitmaps to be displayed. It 
can be found near the top of DIBLIB.CPP. This function takes care of 






realizing the palette of the bitmap to be displayed and then calling 
SetDIBitsToDevice to actually paint the bitmap in a window. 

Realizing a palette is a bit of a juggling act because Windows would like 
to be presented with the palette in the form of a handle to a PALETTE 
object, rather than a pointer to a list of palette entries. As such, 

ShowDIB must allocate space for a logical palette and call CreatePalette 
to get a handle to a suitable object. The new palette must be selected 
into the current device context and then realized with RealizePalette. 
The device context is now ready for a blast from SetDIBitsToDevice, 
which was discussed in detail earlier in this chapter. 

The PrintBitmap function takes care of printing a bitmap to the 
printer device context passed to it. A printer device context is identical 
to a conventional HDC object, except that it references a printer 
rather than your screen. The easiest way to arrive at such an HDC is 
to call PrintDIg, as can be seen in the GetPrintOptions functions of 
VIEWR.CPP. The PrintBitmap function isn’t a great deal more 
complicated—it issues a few printer escapes and calls DibBIt, which 
will be discussed in greater detail later in this chapter. 

In fairness, printing under Windows could easily be a book all by 
itself—Windows’ ostensibly device-independent approach to printing 
arguably makes the whole circus a lot more complex than it needs to 
be. The PrintBitmap function of DIBLIB barely gets its feet wet in the 
torrid seas of Windows’ output functions. 

A printer connected to Windows must be communicated with using a 
combination of escape sequences and GDI calls sent to its HDC. The 
simplest sort of bitmap printing—as illustrated here—requires that you 
send a STARTDOC escape to begin printing, a NEWFRAME escape to 
eject the current page when you’re done printing, and finally an 
ENDDOC escape to terminate printing. The same sorts of GDI calls 
that would be used to paint or draw things in a window can be used 
between the STARTDOC and NEWFRAME escapes to make things 
appear on your printer. 

In this case, the only thing that’s required is a printed bitmap— 
something that’s handled by DibBIt. It will turn up in the next section 
of this chapter, in the WINBIT.CPP module. 
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You’ll probably want to modify the printing facilities of DIBLIB a lot if 
you plan to do something serious with them. 


A digression 
concerning dithering 

The final aspects of DIBLIB to deal with—especially if you like 
complicated software for its own sake—are the three dithering 
functions. Dithering is a complex, somewhat demonic area of image 
processing, and while the examples in this book barely scratch its 
warty, scale-encrusted surface, they should give you a sense of how 
awkward it’s capable of becoming. 

As was touched on in the first chapter of this book, in reducing the 
number of colors in an image down to 256 or fewer, one is 
confronted with the problem of the resulting palette being too small to 
represent the source image’s range of colors. Dithering overcomes 
this by using alternating dots of the available colors to simulate the 
ones that are not available. 

Dithering is a facet of a much larger area of image processing called 
digital halftoning . Conventional halftones, the sorts of pictures that 
turn up in newspaper and magazines, seek to reduce all the gray levels 
in a gray scale photograph to black and white by using spots of 
various sizes. You can see how this works if you look at a newspaper 
photograph through a magnifying glass, or Fig. 2-6 without one. 

Figure 2-6 should also help illustrate why the conventional optical 
halftone process so effective in newspapers isn’t a terribly effective 
way to create low-resolution halftones for display on a computer 
monitor. In a halftone of this type, the number of gray levels that can 
be simulated by halftoning increases with the resolution of the 
image—as the spots get smaller, the halftone gets more convincing. 
However, to reproduce lots of spots, you’d need lots of resolution— 
something computer monitors don’t really have. 

Dithering an image allows you to create somewhat more convincing 
digital halftones in a radically different way. Rather than using spots of 





Figure 2-6 




a b 


A true color image (a) and a conventional halftone of it (b), albeit with 
fairly coarse spots. 


variable size, dithering uses dots in varying patterns. The basic 
premise of dithering was discussed in detail in the first chapter of this 
book. In fact, the tricky aspect of dithering a bitmapped image is the 
method to be used to arrive at alternating patterns of dots that will 
produce a reasonably faithful reproduction of the original image 
without introducing any artifacts , or unwanted image elements, into 
the picture. 

Let’s begin with a look at dithering a gray scale image down to a two- 
color black and white bitmap. This is the simplest sort of dithering. 
There are two ways to go at it, called matrix and error-diffused 
dithering. They’re illustrated in Fig. 2-7. 

It doesn’t take a practiced eye to look at Fig. 2-7 and notice that the 
matrix dither looks a lot worse than the error-diffused dither. What will 
be less apparent in looking at this picture is that matrix dithering is 
worlds faster to perform and requires less memory. 

Matrix dithering is based on a matrix of values that form a comparison 
grid to be imposed upon the source image. In this example, the source 
image is a gray scale bitmap, so each pixel is a value that represents 
the brightness of the pixel in question. This is the Bayer matrix used to 
produce Fig. 2-7 b: 
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A true color image (a) that has been 
dithered with Bayer matrix (b) and 
with a Floyd-Steinberg error-diffusion 
filter (c). 







The Bayer matrix is an array of 64 numbers that lie in the range of 0 
through 63. Each pixel from the source image is shifted right by two 
bits such that its range will also be 0 through 63, and then compared 
to a corresponding element in the matrix based on its position in the 
image. If it’s greater than the element, the pixel is considered to be 
white. If it’s less than the element, the pixel is considered to be black. 
Typically, the result of comparing a gray scale image to a Bayer matrix 
is a new two-color bitmap. 

Here’s a function to do this: 

WORD ComparePixel(WORD x,WORD y,WORD pixel) 

{ 

if((pixel » 2) > bayerPattern[y & 7][x & 7]) 
return(TRUE); 

else 

return(FALSE); 

} 

The problem with matrix dithering is that the matrix knows nothing 
about the nature of the image it’s imposed upon, and as such it 
invariably imposes a fixed pattern, or artifact, on images it’s required 
to process. This is less objectionable in solid areas and line art than it 
is in photographs. Matrix dithering is widely used because it can be 
performed very quickly—it requires nothing more than simple 
processor-level comparisons and bit-shifts to implement. 

Much better dithering can be achieved through the use of error 
diffusion, as illustrated back in Fig. 2-1 c. This is a bit more 
complicated to understand, however. Once again, for the sake of this 
discussion, we’ll allow that the problem is that of dithering a gray scale 
image down to black and white. 

The pixels in a gray scale image can vary from 0 for pure black to 255 
for pure white. Were you to sample all the pixels in a source image, 
you could arrive at the actual range, and a median; that is, a value half 
way between the darkest and lightest pixels. 

The simplest way to reduce a gray scale image to black and white 
would be to compare each pixel against the median—anything below 
the median can be considered to be black and anything above it can be 
considered to be white. Figure 2-8 illustrates this. 
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Applying a threshold median to a gray scale image. The conscientious use 
of 50 sunblock can prevent this condition. 

In thresholding an image, as was done in Fig. 2-8, a great deal of 
detail is lost because the process discards the differences between the 
pixels and the median. In comparing each pixel to the median, there is 
in fact a value by which it differs from the median, called the error. 
These error values represent all the details that thresholding destroys. 

Error-diffusion dithering works by preserving the errors generated by 
thresholding and diffusing them to neighboring pixels. Specifically, 
having derived an error from the thresholding of a pixel, several of its 
surrounding pixels will be adjusted based on a portion of the error. 
These pixels, in turn, will each be thresholded and have their errors 
diffused to neighboring pixels. 

The is a Floyd-Steinberg dithering filter: 

X 7 
3 5 1 

In this diagram, X represents the pixel being thresholded. Notice that 
the numbers add up to 16. In imposing this filter on a pixel, the error 
derived by thresholding the pixel at X is apportioned to the 
surrounding pixels in the ratio of 7 /ieths of the error to the pixel to the 
right of X, 1 ieth of the error to the pixel to the right and one line down 


Figure 2-8 









from X, Xieths of the error to the pixel immediately below X, and heths 
to the pixel to the left and one line down from X. Once the process is 
complete, the filter moves one pixel to the right and begins again. 

Note that the filter never diffuses any errors to pixels that have already 
been processed. 

The result of using an error-diffusion filter, as can be seen back in Fig. 
2-7, is a much more convincing dithered halftone. These things look 
better still at higher resolutions. However, an error-diffusion filter 
requires thousands of times more processor activity per pixel than 
does a matrix filter—error-diffusion dithering is a great deal slower to 
implement. 

Color dithering works pretty much as does the gray scale dithering 
we’ve been looking at herein, except that each of the three color 
indices in a pixel must be dithered separately. 

Because VIEWER uses dithering to deal with screen images, rather 
than sophisticated imaging applications, speed is arguably more 
important than ultimate quality. At least, let’s allow that this is the 
case for the moment—you might want to change the way the dithering 
functions work for your applications. 

The Dither2 function in DIBLIB implements Bayer matrix dithering to 
produce a two color, black-and-white image. Its argument is a handle 
to a device-independent bitmap, and it returns a handle to a new 
device-independent bitmap or NULL if something went wrong. You 
can see how a Bayer matrix is imposed on each pixel in the image in 
its principal for loop. 

The Dither2 function uses two hitherto undiscussed macros to access 
image pixels. Keep in mind that, in creating a two-color final image, 
the dithering function wants to deal with intensity levels, not colors. 

An RGB color can be converted to its corresponding gray level 
through the following macro. 

#define GRAYVALUE( r ,g,b) ((( (r*30)/100) + \ 

((g*59)/100) + \ 

((b*ll)/100))) 








In converting a palette color image to gray scale, there can be no 
more than 256 unique gray scale values in the image. As such, rather 
than deriving the RGB color of each pixel and converting it, Dither2 
can work out the gray levels for each color in the palette and create a 
remapping table of the resulting values. The image pixels will then 
index the table. 

True color images, which don’t have a palette, require that each pixel 
be converted separately. 

Device-independent bitmaps with 16 colors have two pixels stored in 
each byte, as was discussed in the first chapter of this book. These are 
informally referred to as chunky pixels. Chunky pixels are a bit of a 
nuisance to access, and as such the programs in this book use the 
following two macros to keep them in line: 

#define GetChunkyPixel(pxx,nxx) \ 

(!((nxx) & 1)) ? \ 

( ( (pxx) [ (nxx) »1] >> 4) & OxOf) : \ 

( (pxx) [ (nxx) »1] & OxOf) 

#define PutChunkyPixel(pxx,nxx,cxx) (!(nxx & 1)) ? \ 

(pxx[nxx>>l] &= OxOf, pxx[nxx>>l] != \ 

(char)((cxx & OxOf) << 4)) : \ 

(pxx[nxx»l] Sc= OxfO, pxx[nxx>>l] != \ 

(char)(cxx & OxOf)) 


The GetChunkyPixel macro will return the value of pixel nxx from 
line pxx —assuming, of course, that pxx actually points to a line of 
chunky pixels. The PutChunkyPixel macro will set pixel nxx to the 
value cxx in line pxx. These are handy macros to keep in mind when 
you’re dealing with device-independent bitmaps—I wrote them a long 
time ago, and I’ve never had to deal directly with the creeping horror 
of chunky pixels since. 

The Dither 16 function in DIBLIB is, to begin with, slightly misnamed. 
While it returns a 16-color device-independent bitmap, the image itself 
only uses 8 colors. This function performs very fast color Bayer matrix 
dithering using very sneaky bitwise arithmetic. Watch this one closely. 

Allowing that each color in a color palette has three color indices, 
there are eight permutations of colors that can be created by setting 






one or more indices to 255 and the rest to zero. Here’s what such a 
palette would look like: 


static char fixedpalette[]={ 


}; 


o 

o 

o 

//black 

255, 0, 0, 

//red 

0,255, 0, 

//green 

255,255, 0, 

//yellow 

0, 0,255, 

//blue 

255, 0,255, 

//magenta 

0,255,255, 

//cyan 

255,255,255 

//white 


There’s a wealth of color theory in this palette, but you can ignore 
most of it for the moment. 

If the red index in this palette is assigned a weight of one, the green 
index a weight of two, and the blue index a weight of four, each color 
can be seen to be a binary number: 


BLACK 

000 

0 

RED 

001 

1 

GREEN 

010 

2 

YELLOW 

Oil 

3 

BLUE 

100 

4 

MAGENTA 

101 

5 

CYAN 

110 

6 

WHITE 

111 

7 


In performing color dithering of any sort, the most time-consuming 
function is that of color matching. Having created a pixel value by 
thresholding, the dithering function must find the closest available 
color in its palette. There is a function to perform this by calculating 
the distance in color space between two colors, but it’s processor¬ 
intensive and uncomfortably slow. In the case of the eight-color palette 
illustrated here, however, the palette is self-indexing. The source RGB 
color will generate an index into the destination palette simply by 
checking to see which of its color indices are nonzero. 

Specifically, you can locate the closest match to an RGB color in the 
eight color palette like this: 

index=0; 

if(r) index != 1; 
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if(g) index != 2; 
if(b) index != 4; 

Having done this, index is the palette entry number. 

The Dither 16 function implements Bayer matrix dithering using this 
palette. It thresholds each index in the RGB color of a pixel and 
derives an RGB color in which each index is either 0 or 255. Applying 
the foregoing algorithm, it chooses a suitable color from the eight- 
color palette. 

The dithering algorithm used by Dither 16 doesn’t produce superb 
results—they’re recognizable, but they exhibit noticeable dithering 
artifacts. This function is, however, breathtakingly fast. 

The Dither256 function departs from its cousins in that it implements 
error-diffused dithering. It’s possible to perform 256-color matrix 
dithering—you’ll see it at work in Graphic Workshop if you attempt to 
display a true color image on a system with a 256-color Windows 
screen driver installed. The algorithm, while fast, is very funky and 
complex to implement. 

The error diffusion in Dither256 uses a Floyd Steinberg filter of the 
type discussed earlier in this chapter. It’s applied to each index of each 
RGB pixel in the image. This implementation has been designed to be 
fast rather than particularly accurate—it uses 8-bit index samples, 
which can result in a noticeable color shift. While 8 bits is wide 
enough to hold an index value all by itself, the result of an index value 
plus some diffused errors might overflow an 8-bit number. The filter 
works better if the pixels are expanded out to signed integers, but it 
also gets quite a bit slower and more complex to implement. 

The device-independent bitmap created by Dither256 uses a fixed 
orthogonal palette; that is, the same palette is used no matter what 
the color dispersal of the source image is. This results in less than 
optimum color choices in some pathological images, but it allows the 
palette to be searched very quickly. The palette used here has some 
fairly magical properties. Its entries are an even transition from black 
in entry 0 to white in entry 255. The intermediate colors are created 







by varying 3 bits of red, 3 bits of green, and 2 bits of blue—for a total 
of 8 bits, or 256 permutations. 

Because the colors in the orthogonal palette appear at predictable 
locations, it’s easy to match an RGB color to the closest entry in the 
palette. If r, g and b are the color indices of the color to be matched, the 
index into the palette consists of the high-order three bits of r plus the 
high-order three bits of g shifted left three plus the high order two bits of 
b shifted left six. It’s convenient to create a macro to express this: 

#define ORTHOMATCH( r ,g,b) (( (r) & OxOOeO) ! \ 

( ( (g) » 3) & 0x001c) ! \ 

(( (b) » 6) & 0x0003)) 

The actual derivation of an orthogonal palette is handled by the 
GetOrthoPalette function, to be discussed in detail in the next section 
of this chapter. 

When Dither256 error-diffuses its pixels, it creates colors that have to 
be matched to the 256-color orthogonal palette. You can see how this 
works in the principal for loop of the function. Once again, because 
this process just uses a lot of bitwise arithmetic, it’s reasonably fast. 

Each of the dithering functions in DIBLIB can be improved upon. 
Especially if you’re writing applications that you anticipate being run 
on higher-end hardware, you might want to look into improving the 
functions. These implementations have been optimized for speed 
rather than for performance, and in some respects, they can be said to 
date back to a time when computers were slower and people were 
more patient. The Dither 16 function can be rendered a bit more 
attractive if you create a full 16-color palette; that is, with the first 8 
colors duplicated in the upper half of the palette at half intensity. 
Unfortunately, this makes indexing the palette more complex, and the 
resulting function will be noticeably slower. 

WINBIT: touring the glue factory 

Both VIEWER and DIBLIB make calls into the file WINBIT. CPP and 
include its header, WINBIT. H. All the format-specific libraries to be 




discussed later in this book use parts of WINBIT.CPP as well. The 
WINBIT files have appeared informally earlier in this chapter. 

The code police will no doubt look at WINBIT and grunt, muttering 
words like “slothful” and “profligate” under their breath. There are 
aspects of WINBIT that are used by some of the libraries and 
applications that include it, and not by others. As such, each of them 
will have some idle functions in it as a result of using WINBIT. In 
creating real-world software that uses the functions provided by 
WINBIT, you will probably want to split its contents into several 
smaller modules. 

Figure 2-9 illustrates the source code for WINBIT.H and WINBIT.CPP. 


/* 


Windows and OS/2 Bitmapped Graphics 
Common bits 

Copyright (c) 1995 Alchemy Mindworks Inc. 


*/ 

#define VERSION 1 

#define SUBVERSION 0 

#ifndef _WIN32_ 

#define _WIN16_ 

#endif 

/* Note how DLL_EXPORT works -- this slightly odd syntax 
allows the declaration for an exportable function to 
vary between Microsoft and Borland C -- the type modified 
comes before the extern for Microsoft 
C and after it form Borland C. 

*/ 

#ifdef _WIN32_ 

#define PLATFORM 
#define FixedGlobalAlloc(n) 

#define FixedGlobalFree(p) 

#define FixedGlobalRealloc (p,n) 

#define hmemcpy(d,s,n) 

#ifdef _BORLANDC_ 

#define DLL_EXPORT(TYPE) extern 
#else 


"32-bit Windows" 

(char *)malloc(n) 
free(p) 
realloc(p, n) 
memcpy(d,s,n) 

C" WINAPI _export TYPE 
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Figure 2-9A Continued. 

#define DLL_EXPORT(TYPE) TYPE extern WINAPI 
#endif 

typedef char* HPSTR; 

#endif 

ttifdef _WIN16_ 

#define PLATFORM "16-bit Windows" 

#define FixedGlobalAlloc(n) (LPSTR)MAKELONG(0, \ 

GlobalAlloc(GPTR,(DWORD)n)) 

#define FixedGlobalFree(p) GlobalFree((GLOBALHANDLE)\ 

HIWORD((LONG)p)); 

#define FixedGlobalRealloc(p,n) (LPSTR)MAKELONG(0,\ 

GlobalReAlloc((GLOBALHANDLE)HIWORD((LONG)p),(DWORD)n,GPTR)) 
#ifde f BORLANDC 

#define DLL_EXPORT(TYPE) extern "C" FAR PASCAL _export TYPE 

#else 

#define DLL_EXPORT(TYPE) TYPE extern WINAPI 
#endif 

typedef char huge *HPSTR; 

#endif 

#define HELPFILE "WINBIT.HLP" 

#define DITHERBRIGHTNESS 20 

#define DITHERCONTRAST 20 

#define say(s) MessageBox(NULL,s,"Yo...",MB_OK ! MB_ICONSTOP); 

#define saynumber (f,s) {char b[128]; 
sprintf((LPSTR)b,(LPSTR)f,s) a \ 

MessageBox(NULL,b,"Debug Message",MB_OK ! MB_ICONSTOP); } 

#define lmemset(p,c,n) { LPSTR pxx=p; WORD i; \ 

for(i=0;i<n;++i) *pxx++=c; } 

#define lmemcpy(pd,ps,n) { LPSTR pxx=pd,pyy=ps; \ 

WORD i; for(i=0;i<n;++i) *pxx++=*pyy++; } 

#ifndef NOMINMAX 
#ifndef max 

#define max(a,b) (((a)>(b))?(a):(b)) 

#endif 


#ifndef min 
#define min(a,b) 
#endif 
#endif 

#de fine addb(nl,n2) 
#define Wait() 



( ( (a) < (b) ) ? (a) : (b) ) 


max(min((int)(nl)+(int)(n2),255),0) 

{ hHourGlass=LoadCursor(NULL,IDC_WAIT);\ 
hSaveCursor=SetCursor(hHourGlass);\ 










Continued. 

#define NoWait() SetCursor(hSaveCursor) 

#define Initialize() error=NO_ERROR 

#define WIDTHBYTES(i) ( (i+31)/32*4) 

#define PIXELS2BYTES(n) ((n+7)/8) 

#define GREYVALUE(r, g, b) ( ( (r*30)/100) + \ 

((g*59)/100) + \ 

((b*ll)/100))) 

#define ORTHOMATCH(r,g,b) (((r) & OxOOeO)! \ 

( ( (g) » 3) Sc 0x001c) I \ 

(((b) » 6) & 0x0003)) 

#define LPBimage(lpbi) ((HPSTR)lpbi+lpbi->biSize+\ 

(long)(lpbi->biClrUsed*sizeof(RGBQUAD))) 

#ifdef _BORLANDC_ 

#define LPBwidth(lpbi) ((unsigned int)lpbi->biWidth) 

#define LPBdepth(lpbi) ((unsigned int)lpbi->biHeight) 

#define LPBbits(lpbi) ((unsigned int)lpbi->biBitCount) 

#define LPBcolours(lpbi) ((unsigned int)lpbi->biClrUsed) 

#else 

#define LPBwidth(lpbi) (lpbi->biWidth) 

#define LPBdepth(lpbi) (lpbi->biHeight) 

#define LPBbits(lpbi) (lpbi->biBitCount) 

#define LPBcolours(lpbi) (lpbi->biClrUsed) 

#endif 

#define LPBIinewidth(lpbi) (WIDTHBYTES((WORD)lpbi->biWidth*\ 

lpbi->biBitCount)) 

#define LPBcolourmap(lpbi) (LPRGBQUAD)((LPSTR)lpbi+lpbi->biSize) 

#define GetChunkyPixe1(pxx,nxx) \ 

( ! ( (nxx) & 1) ) ? ( ( (pxx) [ (nxx) »1] » 4) & OxOf) : \ 

( (pxx) [ (nxx) »1] Sc OxOf) 

#define PutChunkyPixel(pxx,nxx,cxx) (!(nxx & 1)) ? \ 

(pxx[nxx>>l] Sc= OxOf, pxx[nxx»l] != \ 

(char)((cxx & OxOf) « 4)) : \ 

(pxx[nxx>>l] Sc= OxfO, pxx[nxx»l] != \ 

(char)(cxx & OxOf)) 

#define getword(fh) (getbyte(fh) + (getbyte (fh) «8) ) 

#define getlong(fh) ((long)getbyte(fh) + \ 

( (long) getbyte (fh) «8) + \ 

((long)getbyte(fh)<<16) + \ 

( (long) getbyte (fh) «24) ) 

ttdefine getbufferedword(fh) (getbufferedbyte(fh) + \ 

(getbuf f eredbyte (fh) «8) ) 

#define putbufferedword(n,fh) { putbufferedbyte(n,fh); \ 

putbufferedbyte (n»8, fh) ; } 

#define putword (n, fh) { putbyte (n, fh) ; pu tbyte (n»8, fh) ; } 

#define putlong(n,fh) { putbyte((int)n,fh); \ 

putbyte ( (int) (n»8) , fh) ; \ 
putbyte ( (int) (n»16) , fh) ; \ 
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putbyte ( (int) (n»24) , fh) ; } 


#ifdef NO_ERROR 
#undef NO_ERROR 
#endif 


#define NO_ERROR 0 
#define BAD_OPEN 1 
#define BAD_FILE 2 
#define BAD_READ 3 
#define BAD_ALLOC 4 
#define UNSUPPORTED_FUNCTION 5 
#define BAD_CREATE 6 
#define BAD_WRITE 7 
#define TOO_MANY_BITS 8 
#define MAXRESULTS 9 

#define WRGB_RED 2 
#define WRGB_GREEN 1 
#define WRGB_BLUE 0 

#define RGB_RED 0 
#define RGB_GREEN 1 
#define RGB_BLUE 2 
#define RGB_SIZE 3 

#define STRINGSIZE 260 


typedef struct { 

LPLOGPALETTE pLogPal; 

HANDLE oldPal; 

HANDLE hPal; 

} PALSTATE; 

typedef PALSTATE FAR *LPPALSTATE; 

extern char masktable[8]; 
extern char bittable[8]; 
extern char bayerPattern[8][8] ; 

HANDLE CreateDib(WORD dx,WORD dy,LPSTR palette,WORD bits); 

HANDLE CreateDibHeader(WORD dx,WORD dy,LPSTR palette,WORD bits); 

WORD AdjustDIBits(WORD n); 

WORD RealizeWindowPalette(HDC hdc,LPSTR palette, 

WORD bits,LPPALSTATE ps); 

LPSTR GetErrorText(WORD code); 

LPSTR GetMonoPalette(LPSTR palette); 

LPSTR GetGreyPalette(LPSTR palette); 

LPSTR GetOrthoPalette(LPSTR buffer); 
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int getbyte(int fh) ; 

int getbufferedbyte(int fh); 

int putbyte(WORD byte,int fh) ; 

int putbufferedbyte(WORD byte,int fh) ; 

int GetDibPalette(LPBITMAPINFO lpbi,LPSTR palette); 
int PutDibPalette(LPBITMAPINFO lpbi,LPSTR palette); 
int DibBlt(HDC hdc,int xO,int yO,int dx,int dy, 

HANDLE hdib,int xl,int yl); 


void DeleteFile(LPSTR path); 
void resetbuffer(); 

void UnrealizeWindowPalette(HDC hdc,LPPALSTATE ps) ; 


DLL_EXPORT 

DLL_EXPORT 

DLL_EXPORT 

DLL_EXPORT 

DLL_EXPORT 

DLL_EXPORT 

DLL_EXPORT 

DLL_EXPORT 


(LPSTR) GetFileExtension(); 

(WORD) GetLibraryVersion() ; 

(HANDLE) GetFilelnformation(LPSTR path); 

(HANDLE) ReadGraphicFile(LPSTR path); 

(WORD) WriteGraphicFile(LPSTR path, HANDLE bitmap); 
(WORD) GetError(LPSTR text); 

(LPSTR) GetCopyright(); 

(LPSTR) GetNotice(); 


//bitmap library 

DLL_EXPORT (WORD) GetDibLibraryVersion(); 

DLL_EXPORT (LPSTR) GetDibCopyright(); 

DLL_EXPORT (WORD) CopyPictureToClipboard(HWND hwnd, 
HANDLE hsource); 


DLL_EXPORT 

DLL_EXPORT 

DLL_EXPORT 

DLL_EXPORT 

DLL_EXPORT 

DLL_EXPORT 


(HANDLE) PastePictureFromClipboard(HWND hwnd); 

(WORD) PrintBitmap(HDC hpr,HANDLE handle); 

(HANDLE) Dither256(HANDLE hsource); 

(HANDLE) Ditherl6(HANDLE hsource); 

(HANDLE) Dither2(HANDLE hsource); 

(WORD) ShowDib(HDC hdc,HANDLE handle,WORD x,WORD y); 


DLL_EXPORT 

DLL_EXPORT 

DLL_EXPORT 

DLL_EXPORT 

DLL_EXPORT 

DLL_EXPORT 

DLL_EXPORT 

DLL_EXPORT 


(LPSTR) GetFileExtension(); 

(WORD) GetLibraryVersion(); 

(HANDLE) GetFilelnformation(LPSTR path); 

(HANDLE) ReadGraphicFile(LPSTR path); 

(WORD) WriteGraphicFile(LPSTR path, HANDLE bitmap); 
(WORD) GetError(LPSTR text); 

(LPSTR) GetCopyright(); 

(LPSTR) GetNotice(); 


/* 


Windows and OS/2 Bitmapped Graphics 
Common bits 
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Continued. 

*/ 


ttinclude 
#include 
#include 
#include 
#include 


<windows.h> 
<stdio.h> 
<string.h> 
<stdlib.h> 
"winbit.h" 


#define BYTEBUFFERSIZE 2048 


char masktable[8]={0x80,0x40,0x20,0x10,0x08,0x04,0x02,0x01}; 
char bittable[8]={0x01,0x02,0x04,0x08,0x10,0x20,0x40,0x80}; 


char bayerPattern[8][8] = { 

{ 0,32, 8,40, 2,34,10,42, 

{ 48,16,56,24,50,18,58,26, 

{ 12,44, 4,36,14,46, 6,38, 

{ 60,28,52,20,62,30,54,22, 

{ 3,35,11,43, 1,33, 9,41, 

{ 51,19,59,27,49,17,57,25, 

{ 15,47, 7,39,13,45, 5,37, 

{ 63,31,55,23,61,29,53,21 

}; 


}, 

}, 

}, 

}, 

>, 

}, 

}, 

}, 


char bytebuffer[BYTEBUFFERSIZE]; 
unsigned int bytesleft,nextbyte; 


// Create an empty bitmap 

HANDLE CreateDib(WORD dx,WORD dy,LPSTR palette,WORD bits) 

( 

HANDLE hdibN; 

BITMAPINFOHEADER bi; 

LPBITMAPINFOHEADER lpbi; 

RGBQUAD FAR *pRgb; 

WORD i; 



bits=AdjustDIBits(bits); 


bi.biSize = 

bi.biplanes = 

bi.biBitCount = 

bi.biWidth 

bi.biHeight = 

bi.biCompression 
bi.biXPelsPerMeter = 
bi.biYPelsPerMeter = 
bi.biClrUsed 

(DWORD) ( (l«bits) 
bi.biClrlmportant = 


(DWORD)sizeof(BITMAPINFOHEADER); 
1 ; 

bits; 

(DWORD) dx; 

(DWORD) dy; 

BI_RGB; 

0 ; 

0 ; 

bits > 8 ? 0L : 

& Oxffff); 
bi.biClrUsed; 


bi.biSizeImage=WIDTHBYTES(bi.biWidth*bi.biBitCount)*(long)dy; 







Continued. 

if((hdibN=GlobalAlloc(GMEM_MOVEABLE ! GMEM_DISCARDABLE ! 
GMEM_ZEROINIT,sizeof(BITMAPINFOHEADER) + 

(long)bi.biClrUsed*sizeof(RGBQUAD)+ 
bi.biSizelmage))==NULL) 
return(NULL); 

if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(hdibN)) ==NULL) { 
GlobalFree(hdibN); 
return(NULL); 

} 

lmemcpy( (LPSTR)lpbi, (LPSTR) &bi,sizeof(BITMAPINFOHEADER)) ; 

if(palette != NULL) { 

pRgb = (RGBQUAD FAR *)((LPSTR)lpbi+ 

(unsigned int)lpbi->biSize) ; 

for(i=0;i<bi.biClrUsed;++i) { 

pRgb[i].rgbRed=(char)palette[i*RGB_SIZE+RGB_RED]; 
pRgb[i].rgbGreen=(char)palette[i*RGB_SIZE+RGB_GREEN]; 
pRgb[i].rgbBlue=(char)palette[i*RGB_SIZE+RGB_BLUE]; 
pRgb[i].rgbReserved=0; 

} 

} 

GlobalUnlock(hdibN); 
return(hdibN); 


//create a bitmap header 

HANDLE CreateDibHeader(WORD dx,WORD dy,LPSTR palette,WORD bits) 

{ 

HANDLE hdibN; 

BITMAPINFOHEADER bi; 

LPBITMAPINFOHEADER lpbi; 

RGBQUAD FAR *pRgb; 

WORD i; 


bits=AdjustDIBits(bits); 


bi.biSize 

bi.biplanes 

bi.biBitCount 

bi.biWidth 

bi.biHeight 

bi.biCompression 

bi.biSizelmage 

bi.biXPelsPerMeter 

bi.biYPelsPerMeter 

bi.biClrUsed 

bi.biClrlmportant 


= (DWORD)sizeof(BITMAPINFOHEADER); 
= 1 ; 

= bits; 

= (DWORD)dx; 

= (DWORD)dy; 

= BI_RGB; 

= 0 ; 

= 0 ; 

= 0 ; 

= (DWORD) ( (l«bits) & Oxffff); 

= bi.biClrUsed; 
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if((hdibN=GlobalAlloc(GMEM_MOVEABLE ! GMEMJDISCARDABLE ! 
GMEM_ZEROINIT,sizeof(BITMAPINFOHEADER)+ 

(long)bi.biClrUsed*sizeof(RGBQUAD)))==NULL) 
return(NULL); 

if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(hdibN)) ==NULL) { 
GlobalFree(hdibN); 
return(NULL); 

} 

lmemcpy((LPSTR)lpbi, (LPSTR)&bi,siz eo f(BITMAPINFOHEADER)) ; 

if(palette != NULL) { 

pRgb = (RGBQUAD FAR *)((LPSTR)lpbi+ 

(unsigned int)lpbi->biSize); 

for(i=0;i<bi.biClrUsed;++i) { 

pRgb[i].rgbRed=(char)palette[i*RGB_SIZE+RGB_RED]; 
pRgb[i].rgbGreen=(char)palette[i*RGB_SIZE+RGB_GREEN]; 
pRgb[i].rgbBlue=(char)palette[i*RGB_SIZE+RGB_BLUE]; 
pRgb[i].rgbReserved=0; 

} 

; } 

GlobalUnlock(hdibN); 
return(hdibN); 

; } 

//round bit depths up to legal values for a bitmap 
WORD AdjustDIBits(WORD n) 

i { 

if(n==l) return(1); 

else if(n > 1 && n <= 4) return(4); 
else if(n > 4 && n <= 8) return(8); 
else return(24); 

} 

LPSTR GetMonoPalette(LPSTR palette) 

{ 

static char pal[]="\000\000\000\377\377\377"; 
if(palette != NULL) lmemcpy(palette , pal,6); 
return((LPSTR)pal); 

} 

LPSTR GetGreyPalette(LPSTR palette) 

{ 

LPSTR p; 
int i ; 



p=palette; 
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for(i=0;i<256;++i) { 

p[RGB_RED]=p[RGB_GREEN]=p[RGB_BLUE]=i; 
p+=RGB_SIZE; 

} 

return(palette); 

} 

LPSTR GetOrthoPalette(LPSTR buffer) 

{ 

static int expandbits32[]={ 32,64,96,128,160,192,224,255 }; 
static int expandbitsl6[]={ 64,128,192,255 }; 
static char palette[768]; 
int r,g,b,i,rr,gg,bb; 

for(r=0;r<8;++r) { 

for(g=0;g<8;++g) { 

for(b=0;b<4;++b) { 

rr=expandbits32[r]; 
gg=expandbits32[g]; 
bb=expandbitsl6[b]; 

i=ORTHOMATCH (r<<5 , g<<5 , b«6 ) ; 
palette[i*RGB_SIZE+RGB_RED]=(char)rr; 
palette[i*RGB_SIZE+RGB_GREEN]=(char)gg; 
palette[i*RGB_SIZ E+RGB_BLUE] = (char)bb; 


if(buffer != NULL) lmemcpy(buffer,palette,768); 
return(palette); 

} 

LPSTR GetErrorText(WORD code) 

{ 

switch(code) { 

case NO_ERROR: 

return("No error"); 
case BAD_OPEN: 

return("Error opening the file"); 
case BAD_FILE: 

return("Corrupted or badly formed file"); 
case BAD_READ: 

return("Error reading the file"); 
case BAD_ALLOC: 

return("Error allocating memory"); 
case UNSUPPORTEDJFUNCTION: 

return("Unsupported function"); 
case BAD_CREATE: 

return("Error creating the file"); 
case BAD_WRITE: 
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Continued. 

return("Error writing the file"); 
case TOO_MANY_BITS: 

return("Too many bits for the destination"); 
default: 

return("Unknown error — call 1-800-CAT-FOOD"); 

} 

} 

void DeleteFile(LPSTR path) 

{ 

char b[260]; 

lstrcpy(b,path); 
remove(b) ; 

} 

int GetDibPalette(LPBITMAPINFO lpbi,LPSTR palette) 

{ 

unsigned int i,j; 

j=min (l«lpbi->bmiHeader .biBitCount, 256) ; 

for(i=0;i<j;i++) { 

palette[i*RGB_SIZE+RGB_RED]= 

lpbi->bmiColors[i].rgbRed; 
palette[i*RGB_SIZE+RGB_GREEN]= 

lpbi->bmiColors[i].rgbGreen; 
palette[i*RGB_SIZE+RGB_BLUE]= 

lpbi->bmiColors[i].rgbBlue; 

} 

return(j); 

} 

int PutDibPalette(LPBITMAPINFO lpbi,LPSTR palette) 

{ 

unsigned int i,j; 

j =min(l<<lpbi->bmiHeader.biBitCount,256); 

for(i=0;i<j;i++) { 

lpbi->bmiColors[i].rgbRed= 

palette[i*RGB_SIZE+RGB_RED]; 
lpbi->bmiColors[i].rgbGreen= 

palette[i*RGB_SIZE+RGB_GREEN]; 
lpbi->bmiColors[i].rgbBlue= 

palette[i*RGB_SIZE+RGB_BLUE]; 

} 

return(j); 

} 






, 
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int DibBlt(HDC hdc,int xO,int yO,int dx,int dy, 

HANDLE hdib,int xl,int yl) 

{ 

LPBITMAPINFOHEADER lpbi; 

LPSTR pBuf; 

if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(hdib))==NULL) 
return(FALSE); 

pBuf=(LPSTR)lpbi+(WORD)lpbi->biSize+ 

(WORD)lpbi->biClrUsed*sizeof(RGBQUAD); 

SetDIBitsToDevice(hdc,xO,yO,dx,dy,xl,yl,xl,dy,pBuf, 
(LPBITMAPINFO)lpbi,DIB_RGB_COLORS); 

GlobalUnlock(hdib); 
return(TRUE); 

} 

WORD RealizeWindowPalette(HDC hdc,LPSTR palette, 

WORD bits,LPPALSTATE ps) 

{ 

int i ; 

lmemset((LPSTR)ps,0,sizeof(PALSTATE)); 
if(bits > 8) return(FALSE); 

if((ps->pLogPal=(LPLOGPALETTE)FixedGlobalAlloc 

(sizeof(LOGPALETTE)+256*sizeof(PALETTEENTRY))) == NULL) 
return(FALSE); 

ps->pLogPal->palVersion=0x0300; 
ps->pLogPal->palNumEntries=l<<bits; 

for(i=0;i<ps->pLogPal->palNumEntries;i++) { 

ps->pLogPal->palPalEntry[i].peRed= 
palette[i*RGB_SIZE+RGB_RED]; 
ps->pLogPal->palPalEntry[i].peGreen= 
palette[i*RGB_SIZE+RGB_GREEN]; 
ps->pLogPal->palPalEntry[i].peBlue= 
palette[i*RGB_SIZE+RGB_BLUE]; 
ps->pLogPal->palPalEntry[i].peFlags=0; 

} 

ps->hPal=CreatePalette(ps->pLogPal); 

ps->oldPal=SelectPalette(hdc,ps->hPal,0); 

RealizePalette(hdc); 

return(TRUE); 

} 


void UnrealizeWindowPalette(HDC hdc,LPPALSTATE ps) 
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\ { 

if(ps->pLogPal != NULL) FixedGlobalFree(ps->pLogPal); 
if(ps->oldPal != NULL) SelectPalette(hdc,ps->oldPal,0); 
if(ps->hPal ! = NULL) DeleteObject(ps->hPal); 

j } 

int getbyte(int fh) 

{ 

; char b[1]; 

if(_lread(fh,b,1) != 1) return(EOF); 

else return((int)b[0]); 

} 

void resetbuffer() 

; { 

bytesleft=0; 

i } 

int getbufferedbyte(int fh) 

: { 

if(Ibytesleft) { 

if((bytesleft=_lread(fh,bytebuffer,BYTEBUFFERSIZE))==0) 
return(EOF); 
nextbyte=0; 

; > 

--bytesleft; 

return(bytebuffer[nextbyte++]); 

i > 

int putbyte(WORD byte,int fh) 

{ 

if(_lwrite(fh,(LPSTR)kbyte,1) != 1) return(EOF); 

else return(byte); 

} 



int putbufferedbyte(WORD byte,int fh) 

{ 

if (byte— (WORD) EOF) { 

if(_lwrite(fh,bytebuffer,bytesleft) != bytesleft) 
return(EOF); 
bytesleft=0; 
return(byte); 

} 

else { 

if(bytesleft >= BYTEBUFFERSIZE) { 

if(_lwrite(fh,bytebuffer,bytesleft) != bytesleft) 
return(EOF); 
bytesleft=0; 

} 

bytebuffer[bytesleft++]=(char)byte; 
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return(byte); 

} 

} 


Much of what appears in WINBIT has already been discussed in detail 
earlier in this chapter. It provides the libraries that include it with the 
following functions: 

HANDLE CreateDIB(WORD dx.WORD dy,LPSTR palette,WORD 
bits) —This function returns a handle to a device-independent bitmap 
having the dimensions dx by dy and bits depth of color. The new 
bitmap will have a palette defined by palette, a pointer to a list of 
RGB color values. 

HANDLE CreateDIBHeader(WORD dx.WORD dy,LPSTR 
palette,WORD bits) —This function returns a handle to a device¬ 
independent bitmap header having the dimensions dx by dy and bits 
depth of color. The new bitmap will have a palette defined by palette, 
a pointer to a list of RGB color values. 

WORD AdjustDIBits(WORD bits) —This function rounds its argument 
up to the next higher legal color depth for a device-independent 
bitmap. 

LPSTR GetMonoPalette(LPSTR palette) —This function fills palette 
with a two-color palette, in which the first entry is black and the 
second entry is white. 

LPSTR GetGrayPalette(LPSTR palette) —This function fills palette 
with a 256-color palette in which all the colors are gray, ascending 
from pure black to pure white. 

LPSTR GetOrthoPalette(LPSTR palette) —This function fills palette 
with a 256-color orthogonal palette, as discussed in the previous 
section of this book. 


Figure 2-9B 





LPSTR GetErrorText(WORD code) —This function returns a verbose 
description of an error generated by one of the libraries in this book. 
Call 1-800-CAT-FOOD for more information. 

void DeleteFile(LPSTR path) —This function deletes a file. It’s used 
rather that the standard C language remove to allow for far pointers 
under medium-model Windows applications. 

int GetDibPalette(LPBITMAP!NFO Ipbi,LPSTR palette)— This 
function creates a table of 3-byte RGB colors from a device¬ 
independent bitmap header. Note that it expects a pointer to an 
LPBITMAPINFO object, not an LPBITMAPINFOHEADER. Some 
casting will usually be called for. 

int PutDibPalette(LPBITMAPlNFO Ipbi,LPSTR palette)—This 
function writes a table of 3-byte RGB colors to a device-independent 
bitmap header. 

int DibBlt(HDC hdc.int xO.int yO.int dx.int dy,HANDLE hdib.int xl.int 
yl) —This function paints a device-independent bitmap on a device 
context—-while it can be used to paint in a window, it’s used in this 
book by DIBLIB to print bitmaps. The xO and yO arguments define the 
upper-left corner of the destination rectangle. The dx and dy 
arguments define the dimensions of the destination rectangle. The xl 
and yl arguments define the upper-left corner of the source rectangle, 
which will have the same dimensions as the destination rectangle. The 
hdc argument is the HDC of the device to be printed to. The hdib 
argument is a handle to a device independent bitmap. 

WORD RealizeWindowPalette(HDC hdc,LPSTR 
palette,LPPALSTATE pal) —This function realizes the palette pointed 
to by palette into the device context referenced by hdc. It stores 
several objects in pal, which will subsequently be freed when the 
palette is unrealized. 

void UnrealzeWindowPalette(HDC hdc,LPPALSTATE pal)— This 
function undoes a previous call to RealizeWindowPalette and frees 
the objects it created. 









The WINBIT.CPP file also includes some low-level file handling 
functions that are called by some of the graphic file format libraries. 
The getbyte and putbyte functions will read and write one byte from 
the file handle passed to them. They’re agreeably simple, but 
exceedingly slow if you want to move a lot of bytes around. The 
getbufferedbyte and putbufferedbyte functions implement very 
simple buffering—they’re faster than the streamed file functions for 
working with lots of data, but they still allow files to be accessed one 
byte at a time if need be. The resetbuffer function must be called 
before getbufferedbyte or putbufferedbyte are used, and you must 
call putbufferedbyte with an argument of EOF to empty the buffer if 
you’re writing to a file. These buffered file functions can only be used 
with one file at a time. 


And now for something 
completely different: Warp 

The Windows and OS/2 operating systems sprung from much the 
same malarial swamp and share some common code. While all the 
system calls and data structures differ between Windows and Warp, 
their applications are similarly structured and handle many functions in 
much the same way. This is especially true for the elements of OS/2 
programming to be dealt with in this book—Windows and Warp 
applications are structured similarly, and their approach to graphics is 
comparable in many respects. 

The OS/2 equivalent to a Windows device-independent bitmap was 
discussed in detail in chapter 1. Figure 2-10 illustrates what VIEWER 
looks like when it turns up as an OS/2 application. 

The structure of VIEWER.C for OS/2, illustrated in Fig. 2-10, is 
essentially the same as that of VIEWER.CPP for Windows—at least, it 
is as far as it deals with loading, saving, and displaying bitmaps. The 
OS/2 implementation of VIEWER does not include functions to 
manage the clipboard or to print bitmaps. 

The procedure for displaying a bitmap under OS/2 is similar to the 
one discussed earlier in this chapter for Windows application using 
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An image file viewer as it appears in OS/2. 


BitBIt. The OS/2 equivalent to a device context handle is a 
presentation space handle, or HPS object. As with displaying bitmaps 
under Windows, the structure of the bitmap structure maintained by an 
HPS should be considered mysterious and best left that way. An OS/2 
application that wants to display a bitmap must call GpiCreateBitmap 
to generate a handle to a device-dependent bitmap with a structure 
that corresponds to the current presentation space. This bitmap can 
be passed to GpiBitBIt to paint an image to the client window of the 
software in question. 

As would be the case with using BitBIt under Windows, the process of 
converting a large bitmap to its device-dependent form each time the 
client window of VIEWER is to be updated is fairly time-consuming. 
While it’s not presented in VIEWER, you can improve on the 
performance of a display application considerably by creating a device¬ 
dependent bitmap and leaving it in memory for as long as its parent 
device-independent bitmap exists. This will get past the steps involved 








in recreating it each time, although it represents one more object to 
keep track of and one more thing for OS/2’s memory manager to 
juggle if memory starts running low. 

As with the Windows version of VIEWER, all the work of maintaining 
the client area of the application is handled in the WM_PAINT case 
of the primary message handler. The DibBIt function paints a bitmap 
to the screen, albeit using somewhat different arguments. It resides in 
the DIBLIBW.DLL, which we’ll get to in detail in a moment. 

The OS/2 palette manager works somewhat differently than does the 
palette manager for Windows. It will allow one application to shanghai 
the hardware palette resources to some extent if need be, and when a 
new palette is realized, you might see the other objects visible on your 
screen change color. A device-dependent bitmap is created based on 
the currently realized palette in the presentation space of the bitmap. 
For this reason, a suitable palette must be created and realized before 
a device-dependent bitmap can be created. 

Allowing that image is an image handle, hps is a presentation space 
handle, and hpsMemory is a memory-based presentation space, these 
are the OS/2 GPI calls involved in painting a bitmap to the client area 
of a window. 

To begin with, the bitmap handle must be locked—for reasons that will 
be discussed later in this chapter, this doesn’t actually do anything in 
the code as it’s implemented here, but it’s useful to keep it as a stub: 

LPBITMAPINFOHEADER lpbi=NULL; 

lpbi=(LPBITMAPINFOHEADER)GlobalLock(image); 


Note that LPBITMAPINFOHEADER is defined as a pointer to a 
BITMAPINFOHEADER2 object in the OS/2 version of the code in this 
book. 

With the bitmap locked, it’s possible to determine the color palette 
that will ultimately have to be realized into the presentation space for 
the destination window. Fortunately, the array of RGB2 objects that 






follows a BITMAPINF0HEADER2 object is the format that GPI 
requires to create a palette—the call is relatively simple: 


HPAL hpal=NULLHANDLE; 

hpal = GpiCreatePalette(hab, 
LCOL_PURECOLOR, 
LCOLF_CONSECRGB, 

LPBcolors(lpbi), 

(PULONG)LPBcolormap(lpbi)); 


The palette can now be selected into hpsMemory, such that when a 
bitmap is created it will have the correct palette: 


GpiSelectPalette(hpsMemory,hpal); 


The GpiBitBIt function requires a handle to a device-dependent 
bitmap, as was discussed earlier in this chapter. This can now be 
created: 

HBITMAP hBitmap=NULLHANDLE; 

hBitmap=GpiCreateBitmap(hpsMemory, 

(PBITMAPINF0HEADER2)lpbi, 

CBM_INIT, 

LPBimage(lpbi), 

(PBITMAPINF02)lpbi); 

The whole juggling act is almost over. The new bitmap handle must be 
selected into the source presentation space, like this: 

GpiS e tBitmap(hpsMemory,hBitmap); 

The palette should be selected into the destination presentation space 
so it, too, will have the right set of colors on hand: 


GpiSelectPalette(hps,hpal); 


Everything is now ready to actually realize the palette that has been 
selected into the presentation space for the client window. This is 
where Warp gets to see how close it can get the real palette of the 
window to the palette that’s been requested: 

WinRealizePalette(hwnd,hps,&1); 



The number of colors that have actually been remapped, and are thus 
available, will be stored in the long integer pointed to by the third 
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argument. This number isn’t used in the DibBIt function provided by 
DIBLIBW. 

We’re now ready to actually do something. Here’s the call to 
GpiBitBIt. This assumes the availability of a few more objects. The 
prectl pointer points to a RECTL object that defines the client area of 
the window to receive this bitmap. The values sx and sy are the offset 
from the upper-left corner of the bitmap to start copying from—in 
practical terms, they’re the values returned by querying the window’s 
scroll bars. 

POINTL point[3]; 
int x,y; 

x=LPBwidth(lpbi); 
y=LPBdepth(lpbi); 

point[0].x=-sx; 

point[0].y=(int)prectl->yTop-(int)y+(int)sy; 
point[1].x=x-(int)sx; 

point[1].y=y+(int)prectl->yTop-(int)y+(int)sy; 
point[2]. x=0; 
point[2]. y=0; 

GpiBitBIt(hps,hpsMemory,3,&point[0],ROP_SRCCOPY,BBO_IGNORE); 

The GpiBitBIt function copies bitmaps between presentation spaces, 
which is why the source bitmap created a bit earlier had to be selected 
in hpsMemory before anything could be done with it. Its first and 
second arguments are handles to the destination and source 
presentation spaces respectively. The third argument is the number of 
POINTL objects that GpiBitBIt can expect to be pointed to by its 
fourth argument. 

The array of points passed to GpiBitBIt tell it the source and 
destination rectangles to use for copying. Unlike Windows, which 
maintains BitBIt for simple copying and StretchBIt for copying that 
requires that the source bitmap be resized, OS/2 only has one bit 
block transfer function—it takes care of both cases. In this example, 
no resizing is necessary. 

A simple bit copy, then, requires three points. The first one defines 
the lower-left corner of the destination rectangle in the destination 
presentation space. The second one defines the upper-right corner of 
the destination rectangle. The third defines the lower-left corner of the 
source rectangle. 











As an aside, this will seem a bit unusual to Windows programmers. 
Windows allows that the origin for drawing in a window is the upper- 
left corner—positive vertical values move toward the bottom of a 
window. For reasons that would probably make sense to you if you 
worked for IBM, OS/2 has the origin for drawing in the lower-left 
corner of a window; that is, it works in traditional Cartesian 
coordinates—positive vertical numbers move toward the top of a 
window. This is probably scientifically more justifiable, but it’s often 
confusing as hell. 


The latter two arguments to GpiBitBIt are constants. The 
ROP_SRCCOPY value tells it to copy the bitmap in question from the 
source to the destination presentation space and paint over the 
affected pixels in the destination bitmap. Other arguments are 
available to AND, OR, XOR, and invert the pixels of the source and 
destination bitmaps, things we need not get into here. 


The final argument to GpiBitBIt, BBOJGNORE in this case, tells 
Warp’s GPI what to do if the bitmap is to be resized. Inasmuch as this 
bitmap won’t be resized, GpiBitBIt need not concern itself with this 
eventuality. 


The complete DIBLIBW.CPP source listing can be found in Fig. 2-11. 
This is structurally similar to DIBLIB for Windows, discussed earlier in 
this chapter. Its DibBIt function uses the GPI calls that have been 
discussed in this section. 

Figure 2-11 /* 

Bitmap Library 

Copyright (c) 1995 Alchemy Mindworks Inc. 


#define INCLJDOSFILEMGR 
#define INCL_DOSMEMMGR 
#define INCL_DOSERRORS 
#define INCL_DOSPROCESS 
#define INCL_WIN 
#define INCL_GPI 
#define INCL_PM 



The DIBLIBW.CPP library. 
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#include <os2.h> 

#include <stdio.h> 

#include <string.h> 

#include <stdlib.h> 

#include <fcntl.h> 

#include <io.h> 

#include "os2bit.h" 

#define DestroyAllObjects(success) {\ 

if(hsource != NULL && Ipbs != NULL) GlobalUnlock(hsource);\ 
if(hdest != NULL && lpbd ! = NULL) GlobalUnlock(hdest);\ 
if(hdest != NULL && !success) GlobalFree(hdest);\ 

} 

HANDLE DLL_EXPORT InvertBitmap(HANDLE hsource) 

{ 

HANDLE hdest=NULL; 

LPBITMAPINFOHEADER lpbs=NULL,lpbd=NULL; 

HPSTR ps,pd; 
char palette[768] ; 
unsigned int i,j; 

if((lpbs=(LPBITMAPINFOHEADER)GlobalLock(hsource))==NULL) { 
DestroyAllObjects(FALSE); 
return(NULL); 


GetDibPalette((LPBITMAPINFO)lpbs,palette); 

if((hdest=CreateDib((WORD)LPBwidth(lpbs),(WORD)LPBdepth(lpbs), 
palette,LPBbits(lpbs)))==NULL) { 

DestroyAllObjects(FALSE); 
return(NULL); 


if((lpbd=(LPBITMAPINFOHEADER)GlobalLock(hdest))==NULL) { 
DestroyAllObjects(FALSE); 
return(NULL); 


ps=LPBimage(lpbs); 
pd=LPBimage(lpbd); 

for(i=0;i<LPBdepth(lpbs);++i) { 

for(j=0;j<LPBwidth(lpbs);++j) pd[j]=ps[j] A Oxff; 

ps+=LPBlinewidth(lpbs); 
pd+=LPBlinewidth(lpbd); 


DestroyAllObjects(TRUE); 


Figure 2-11 
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return(hdest); 

} 

#undef DestroyAllObjects() 

void DiffuseFloyd(HPSTR linel,HPSTR line2,int x, int y, int r, 
int g,int b, int mr,int mg,int mb,int width,int depth) 

{ 

int dr, dg, db, xpos, vr, vg, vb; 

dr= (r-mr) »4 ; 
dg= (g-mg) »4 ; 
db=(b-mb)>>4; 

vr=dr«l ; 
vg=dg«l; 
vb=db<<l; 

if((x+l) < width ScSc (y+1) < depth) { 
xpos=RGB_SIZE*(x+1); 

line2[xpos+WRGB_RED] =addb(line2[xpos+WRGB_RED],dr); 
line2[xpos+WRGB_GREEN]=addb(line2[xpos+WRGB_GREEN],dg); 
line2[xpos+WRGB_BLUE] =addb(line2[xpos+WRGB_BLUE],db); 

} 

dr+=vr; dg+=vg; db+=vb; 

if((x-l) > 0 && (y+1) < depth) { 
xpos=RGB_SIZE*(x-1); 

line2[xpos+WRGB_RED] =addb(line2[xpos+WRGB_RED],dr); 
line2[xpos +WRGB_GREEN]=addb(line2[xpo s +WRGB_GREEN] ,dg) ; 
line2[xpos+WRGB_BLUE] =addb(line2[xpos+WRGB_BLUE],db); 

} 

dr+=vr; dg+=vg; db+ =vb; 

if((y+1) < depth) { 

xpos=RGB_SIZE*(x); 

line2[xpos+WRGB_RED] =addb(line2[xpos+WRGB_RED],dr); 
line2[xpos +WRGB_GREEN]=addb(line2[xpos + WRGB_GREEN] ,dg) ; 
line2[xpos+WRGB_BLUE] =addb(line2[xpos+WRGB_BLUE],db); 

} 

dr+=vr; dg+=vg; db+=vb; 

if((x+1) < width) { 

xpos=RGB_SIZE*(x+1); 

linel[xpos+WRGB_RED] =addb(linel[xpos+WRGB_RED],dr); 
linel[xpos +WRGB_GREEN]=addb(linel[xpos +WRGB_GREEN] ,dg) ; 
linel[xpos +WRGB_BLUE] =addb(linel[xpos+WRGB_BLUE] ,db) ; 

} 

} 


.t 
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#define DestroyAllObjects(success) {\ 

if(hsource != NULL && lpbs != NULL) GlobalUnlock(hsource);\ 
if(hdest != NULL && lpbd != NULL) GlobalUnlock(hdest);\ 
if(hdest != NULL && Isuccess) GlobalFree(hdest);\ 

} 

HANDLE DuplicateImage(HANDLE hsource) 

{ 

HANDLE hdest=NULL; 

LPBITMAPINFOHEADER lpbs=NULL,lpbd=NULL; 

HPSTR ps,pd; 
char palette[768]; 
unsigned int i; 

if((lpbs=(LPBITMAPINFOHEADER)GlobalLock(hsource))==NULL) { 
DestroyAllObjects(FALSE); 
return(NULL); 

} 

GetDibPalette((LPBITMAPINFO)lpbs,palette); 

if((hdest=CreateDib(LPBwidth(lpbs),LPBdepth(lpbs), 
palette,LPBbits(lpbs)))==NULL) { 

DestroyAllObjects(FALSE); 
return(NULL); 

} 

if((lpbd=(LPBITMAPINFOHEADER)GlobalLock(hdest))==NULL) { 
DestroyAllObjects(NULL); 
return(NULL); 

} 

ps=LPBimage(lpbs); 
pd=LPBimage(lpbd); 

for(i=0;i<LPBdepth(lpbs);++i) { 

hmemcpy(pd,ps,LPBlinewidth(lpbs)); 

ps+=(long)LPBlinewidth(lpbs); 
pd+=(long)LPBlinewidth(lpbs); 

} 

DestroyAllObjects(TRUE); 
return(hdest); 

} 

#undef DestroyAllObjects() 

#define DestroyAllObjects(success) {\ 

if(hsource != NULL && lpbs != NULL) GlobalUnlock(hsource);\ 
if(hsource != NULL && lpbd != NULL) GlobalFree(hsource);\ 
if(hdest != NULL && lpbd != NULL) GlobalUnlock(hdest);\ 
if(hdest != NULL && Isuccess) GlobalFree(hdest);\ 


Figure 2-11 
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} 

HANDLE DLL_EXPORT Dither256(HANDLE hsource) 

{ 

HANDLE hde s t =NULL; 

LPBITMAPINFOHEADER lpbs=NULL,lpbd=NULL; 

LPSTR pr; 

HPSTR source=NULL,dest=NULL; 
char palette[768]; 
unsigned int k, r, g,b,mr,mg,mb; 
unsigned int i,j; 

if((lpbs=(LPBITMAPINFOHEADER)GlobalLock(hsource))==NULL) 
return(NULL); 

GlobalUnlock(hsource); 
lpbs=NULL; 

if((hsource=DuplicateImage(hsource))==NULL) 
return(NULL); 

if((Ipbs=(LPBITMAPINFOHEADER)GlobalLock(hsource))==NULL) { 
DestroyAl10bjects(FALSE); 
return(NULL); 

} 

GetOrthoPalette(palette); 

if((hdest=CreateDib(LPBwidth(Ipbs),LPBdepth(lpbs), 
palette,8))==NULL) { 

DestroyAllObjects(FALSE); 
return(NULL); 

} 

if((lpbd=(LPBITMAPINFOHEADER)GlobalLock(hdest))==NULL) { 
DestroyAllObjects(FALSE); 
return(NULL); 

} 

source=LPBimage(lpbs); 
dest=LPBimage(lpbd); 

for(i=0;i<LPBdepth(lpbs);++i) { 

for(j =0;j<LPBwidth(lpbs);++j) { 

k=RGB_SIZE*j; 
resource[k+WRGB_RED]; 
g=source[k+WRGB_GREEN]; 
b=source[k+WRGB_BLUE]; 

k=ORTHOMATCH(r,g,b); 
pr=palette+RGB_SIZE*k; 

dest[j]=k; 
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mr=pr[RGB_RED]; 
mg=pr[RGB_GREEN]; 
mb=pr[RGB_BLUE]; 

DiffuseFloyd(source, 

source+(long)LPBlinewidth(lpbs), 

j / 

i, 
r, 

g/ 

b. 


nig, 

mb, 

LPBwidth(lpbs), 

LPBdepth(lpbs)); 

} 

source+=(long)LPBlinewidth(lpbs); 
dest+=(long)LPBlinewidth(lpbd); 

} 

DestroyAllObjects(TRUE); 
return(hdest); 

} 

#undef DestroyAllObjects(); 

#define DestroyAllObjects(success) {\ 

if(hsource != NULL && lpbs != NULL) GlobalUnlock(hsource);\ 
if(hdest != NULL && lpbd != NULL) GlobalUnlock(hdest);\ 
if(hdest != NULL && [success) GlobalFree(hdest);\ 

} 

HANDLE DLL_EXPORT Ditherl6(HANDLE hsource) 

{ 

static char fixedpalette[]={ 

0, 0, 0, 

255, 0, 0, 

0,255, 0, 

255,255, 0, 

0, 0,255, 

255, 0,255, 

0,255,255, 

255,255,255 
} ; 


HANDLE hdest=NULL; 

LPBITMAPINFOHEADER lpbs=NULL,lpbd=NULL; 
LPSTR pi; 

HPSTR ps,pd,pr; 

char palette[768]; 

unsigned int ditherlinewidth; 
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unsigned int i,j,m,n; 
int r,g,b,bits; 

if((lpbs=(LPBITMAPINFOHEADER)GlobalLock(hsource))==NULL) { 
DestroyAllObjects(FALSE); 
return(NULL); 

} 

bits=(int)LPBbits(lpbs); 

GetDibPalette((LPBITMAPINFO)lpbs,palette); 

if((hdest=CreateDib((WORD)LPBwidth(lpbs),LPBdepth(lpbs), 
fixedpalette,4))==NULL) { 

DestroyAllObjects(FALSE); 
return(NULL); 

> 

ditherlinewidth=PIXELS2BYTES(LPBwidth(lpbs))«2; 
if(ditherlinewidth & 0x0003) 

ditherlinewidth=(ditherlinewidth ! 3)+l; 

if((lpbd=(LPBITMAPINFOHEADER)GlobalLock(hdest))==NULL) { 
DestroyAllObjects(FALSE); 
return(NULL); 

} 

ps=LPBimage(lpbs); 
pd=LPBimage(lpbd); 

for(i = 0;i<LPBdepth(lpbs);++i) { 
pr=ps; 

ps+=LPBlinewidth(lpbs); 
if(bits > 8) { 

for(j =0;j <LPBwidth(lpbs);++j) { 

r=pr[WRGBJRED]; 
g=pr[WRGB_GREEN]; 
b=pr[WRGB_BLUE]; 

m=(bayerPattern[j & 0x0007][i & 0x0007]<<2); 
n=0 ; 

if(r > m) n != 0x01; 
if(g > m) n != 0x02; 
if(b > m) n != 0x04; 

pr+=RGB_SIZE; 

PutChunkyPixel(pd,j , n); 

} 
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} 

else { 

for(j=0;j<LPBwidth(lpbs);+ + j) { 

pl=palette+*pr++*RGB_SIZE; 
r=pl[RGB_RED]; 
g=pl[RGB_GREEN]; 
b=pl[RGB_BLUE]; 

m=(bayerPattern[j & 0x0007][i & 0x0007]<<2); 
n=0 ; 


} 


if(r > m) n 
if(g > m) n 
if(b > m) n 


0x01; 

0x02; 

0x04; 


PutChunkyPixel(pd,j,n); 


pd+=LPBlinewidth(lpbd); 

} 

DestroyAllObjects(TRUE); 
return(hdest); 

} 

#undef DestroyAllObjects() 

#define DestroyAllObjects(success) { \ 

if(hsource != NULL && lpbs != NULL) GlobalUnlock(hsource);\ 
if(source != NULL && [success) GlobalFree(hsource);\ 
if(hdest != NULL && lpbd != NULL) GlobalUnlock(hdest);\ 
if(hdest != NULL && [success) GlobalFree(hdest);\ 

} 

HANDLE DLL_EXPORT Dither2(HANDLE hsource) 

{ 

HANDLE hdest=NULL; 

LPBITMAPINFOHEADER lpbs=NULL,lpbd=NULL; 

HPSTR source=NULL / dest^NULL,pss; 
double a,fac; 

char palette[768],greylevel[256]; 
char remap[256]; 
unsigned int i,j,n; 
int bits; 


if((lpbs=(LPBITMAPINFOHEADER)GlobalLock(hsource))==NULL) { 
DestroyAllObjects(FALSE); 
return(NULL); 

} 


Figure 2-11 



bits=(int)LPBbits(lpbs); 







Figure 2-11 Continued. 

GetMonoPalette(palette); 

if((hdest=CreateDib((WORD)LPBwidth(lpbs),(WORD)LPBdepth(lpbs), 
palette,1))==NULL) { 

DestroyAllObjects(FALSE); 
return(NULL); 

} 

if((lpbd=(LPBITMAPINFOHEADER)GlobalLock(hdest))==NULL) { 

DestroyAl10bjects(FALSE); 
return(NULL); 

} 

source=LPBimage(lpbs); 
dest=LPBimage(lpbd); 

GetDibPalette((LPBITMAPINFO)lpbs,palette); 
for(i=0;i<256;++i) 

greylevel[i]=GREYVALUE(palette[i*RGB_SIZE+RGB_RED], 

palette[i*RGB_SIZE+RGB_GREEN], 
palette[i*RGB_SIZE+RGB_BLUE]); 

fac=256/(256-((double)DITHERCONTRAST*2)); 
a=(double)DITHERBRIGHTNESS-(double)DITHERCONTRAST; 

for(i=0;i<256;++i) { 

if(a > 254) n=254; 
else if(a < 1) n=l; 
else n=(unsigned int)a; 
remap[i]=n; 
a+=fac; 

} 

for(i=0;i<LPBdepth(lpbs);++i) { 

for(j=0;j<LPBwidth(lpbs);++j) { 

if(bits==24) { 

pss=source+(long)j*RGB_SIZE; 
n=GREYVALUE(pss[WRGB_RED], 

pss[WRGB_GREEN], 
pss[RGB_BLUE]); 

} 

else if(bits==8) n=greylevel[source[j]]; 
else n=greylevel[GetChunkyPixel(source,j)]; 

if ( (n=remap [n] »2) > 

bayerPattern[i & 0x0007][j & 0x0007]) 
dest[j>>3] Sc= ~masktable[j & 0x0007]; 

else 

dest[j>>3] != masktable[j & 0x0007]; 

} 





Displaying bitmapped graphics 



Continued. 

source+=LPBlinewidth(lpbs); 
dest+=LPBlinewidth(lpbd); 

} 

DestroyAllObjects(TRUE); 
return(hdest); 

} 

#undef DestroyAllObjects(); 

WORD DLL_EXPORT GetDibLibraryVersion() 

{ 

return((VERSION « 8) ! SUBVERSION); 

} 

LPSTR DLL_EXPORT GetDibCopyright() 

{ 

return("Copyright (c) 1995 Alchemy Mindworks Inc."); 

} 

#define DestroyAllObjects() { if(hpal != NULLHANDLE) 

GpiDeletePalette(GpiSelectPalette(hpsMemory,NULLHANDLE));\ 
if(hBitmap != NULLHANDLE) 

GpiDeleteBitmap(GpiSetBitmap(hpsMemory,NULLHANDLE));\ 
if(lpbi != NULL) GlobalUnlock(image);\ 

} 

WORD DLL_EXPORT DibBlt(HWND hwnd,HAB hab,HPS hps,HPS hpsMemory,HANDLE 
image,int sx,int sy,PRECTL prectl) 

{ 

HPAL hpal=NULLHANDLE; 

HBITMAP hBitmap=NULLHANDLE; 

LPBITMAPINFOHEADER lpbi=NULL; 

POINTL point[3]; 
unsigned long 1; 
int x,y; 

if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(image)) ==NULL) { 
DestroyAllObjects(); 
return(FALSE); 

} 

if((hpal = GpiCreatePalette(hab, 

LCOL_PURECOLOR, 

LCOLF_CONSECRGB, 

LPBcolours(lpbi), 

(PULONG)LPBcolourmap(lpbi))) == NULLHANDLE) { 
DestroyAllObjects(); 
return(FALSE); 

} 

GpiSelectPalette(hpsMemory,hpal); 


Figure 2-11 
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Continued. 

if((hBitmap=GpiCreateBitmap(hpsMemory,(PBITMAPINFOHEADER2)lpbi, 
CBM_INIT, 

LPBimage(lpbi), 

(PBITMAPINF02)lpbi)) == NULLHANDLE) { 
DestroyAllObjects(); 
return(FALSE); 

} 

if(GpiSetBitmap(hpsMemory,hBitmap) == HBM_ERROR) { 

DestroyAllObjects(); 
return(FALSE); 

} 

GpiSelectPalette(hps,hpal) ; 

WinRealizePalette(hwnd,hps,&1); 

x=LPBwidth(lpbi); 
y=LPBdepth(lpbi); 

point[0].x=-sx; 

point[0].y=(int)prectl->yTop-(int)y+(int)sy; 
point[1].x=x-(int)sx; 

point[1].y=y+(int)prectl->yTop-(int)y+(int)sy; 
point[2].x=0; 
point[2].y=0; 

GpiBitBlt(hps,hpsMemory,3,&point[0],ROP_SRCCOPY,BBO_IGNORE); 
DestroyAllObjects(); 
return(TRUE); 

} 

#undef DestroyAllObj ects() 


Both VIEWER and DIBLIBW make calls to functions from 
OS2BIT.CPP, the Warp equivalent of WINBIT.CPP discussed earlier. 
Virtually everything it does is equivalent, except that it provides the 
stub functions that allocate, lock, unlock, and free global memory. 

While memory is handled under Warp in a way that’s comparable to 
what takes place under Windows, it doesn’t actually present itself to 
applications using quite the same interface. Warp doesn’t have a 
general memory handle object—rather, memory is referenced by 






pointers that are locked, or committed , when the memory they point 
to is to be accessed. For this reason, the structure used for memory 
throughout this book doesn’t port cleanly to OS/2. 

To keep the examples in this book down to a manageable level of 
complexity, I’ve defined a HANDLE object under OS/2 as a pointer. 
The GlobalAlloc function returns a locked pointer, the GlobalLock 
function does nothing more than return the pointer passed to it, the 
GlobalUnlock function does nothing at all, and the GlobalFree 
function frees the pointer. 

You might want to change the way these functions operate, depending 
on your use of the libraries in this book. The approach used here is 
easily understood, but it arguably makes less than optimum use of 
Warp’s memory. 

. Going for the one 

To work with the example functions and libraries discussed in this 
book, you should copy the contents of the \WINBIT or \OS2BIT 
directories to your hard drive, depending on whether you’re running 
Window or OS/2. Note that these directories have subdirectories—if 
you’re copying the files from a DOS prompt, use XCOPY with the /S 
option to preserve the directory structure. Should you have cause to 
rebuild any of the graphic format libraries, you’ll find that everything’s 
a lot easier to deal with if you keep the same directory structure. 

Note that you can place the WINBIT or OS2BIT directory in the 
parent directory for your compiler if you like. 

It’s not necessary to rebuild any of the libraries unless you want to 
change how they work—compiled DLLs are included with the 
\ WINBIT and \OS2BIT directory contents. If you don’t have an 
interest in digging into the workings of these libraries, you can 
probably stop reading once you get to the end of this chapter. 











To have a Windows application read JPEG files, for example, you 
would have to do the following: 

© Include winbit.h in your application’s source file. 

© Copy JPGLIB16.DLL or JPGLIB32.DLL to the parent directory of 
your application, depending on whether yours is a 16- or 32-bit 
application. 

© Add JPGLIB16.LIB or JPGLIB32.LIB to the project or MAKE file 
for your application. 

© Call ReadGraphicFile from your application when you want to 
read a JPEG file. 

This is all pretty simple stuff—there are bacteria and some lawyers 
who can manage it. If you want to use some of the functions provided 
by DIBLIB, you’ll have to copy DIBLIB16.DLL or DIBLIB32.DLL to 
your application’s directory and add DIBLIB16.LIB or DIBLIB32.LIB 
to the project or MAKE file for your application as well. 

Programmers working in OS/2 can follow the same procedure, except 
that the DLL and LIB names end in W, rather than 16 or 32. 

There are actually aspects of the libraries you might find cause to 
modify, depending upon how sophisticated your imaging applications 
are. These will be discussed as they come up throughout this book. 

For the most part, however, they can be used as they stand. 

You’ll probably also find it helpful to lift the calling code for the library 
functions from VIEWER.GPP or VIEWER.C. 

If you do decide to rebuild the libraries for any reason, there are a 
number of important things to keep in mind. The first is that the TIFF, 
JPEG, and PNG libraries are based in part on code written by parties 
other than myself, in most cases with no specific intent of it ever being 
used under Windows or OS/2. In some cases, I’ve modified these 
packages or added files to them to make them work with Windows and 
Warp. They all compile and run properly, but they might generate a 
few spurious warnings, depending upon the revision of your compiler. 
You can ignore these. 






If you compile both the 16- and 32-bit Windows libraries, you must 
build the entire library when you switch models. The object files 
generated by the library projects have the same names, but your 
compiler will complain if you ask it to include 16-bit object files in a 
32-bit library, for example. 

Finally, check out the Notice function in VIEWER for any libraries you 
decide to use in your own applications. There are a legal catches 
attached to some of them, and in the cases of the libraries that include 
third-party code, you should be sure to display the copyright and 
credit messages that identify who worked on what. 


















F all the bitmapped image file formats to be discussed in this 
book, the GIF format is arguably the most fun. There are more 
pictures available as GIF files—most of them free for the asking—than 
there are in any other file format on the planet. The content of some 
of them is a bit contentious, however. 

The acronym GIF stands for “graphic interchange format.” It’s 
pronounced “jif,” if you believe the documentation from CompuServe. 
This seems to assume that the word “graphics” is spelled with a “j” in 
some dialects of English. Aside from being a questionable 
pronunciation, it’s not even a particularly accurate allusion. For 
reasons that will be discussed later in this chapter, GIF files take more 
time to unpack than do many other image file formats. 

The GIF format was created at the behest of CompuServe as a 
medium for exchanging pictures by modem. CompuServe, the huge 
dial-up database, is very much into modems, and still more so into the 
connect charges that spring from their use. CompuServe is always 
interested in phenomenon that might increase the number of minutes 
people spend online. 

Acronyms work both ways—the originator of the GIF standard 
frequently encounters its name written other than it would like, as 
CompuServe; that is, with a dollar sign in the middle. 

The notion that people might become interested in exchanging 
pictures by modem, if only there was a reliable, flexible way to do so, 
was one of the more inspired ideas in the ongoing process to run up 
the Visa balances of the western world. Since the inception of GIF, 
terrabytes worth of scanned images have turned up in this format. The 
GIF standard, not being attached to any one manufacturer’s hardware, 
can be used by pretty well anything. Software to view GIF images is 
available for pretty well every computer that has graphics facilities— 
everything from entry-level Apples to Sun workstations. 

While the GIF standard was originated by CompuServe, it hasn’t 
stayed there exclusively. Most bulletin boards have image conferences 
with buckets of GIF files in them. There are numerous boards that 
have little else. 











CompuServe GIF files 




The history of personal computer communications has analogies in 
the history of print, which went through many of the same 
convolutions back when paper and ink and hot lead type were really 
state of the art. The foundations of contemporary printing can be seen 
in 19th century Europe, when the first high-speed mechanical printing 
presses were created. While these machines were available to anyone 
with the money to afford them, their extreme cost didn’t see them 
become widely used until almost the turn of the century. Their limited 
acceptance prior to that can be found to a large extent in the printing 
of erotica, as the people who bought these books could afford to 
support them. 

The GIF image file format has seen itself used for similar purposes. Of 
the innumerable GIF files wandering the phone lines of the planet, the 
vast majority are of nude women. Clearly this was not built into the 
original specification—it’s just the way people have chosen to use GIF. 
Of course, it has given GIF files in general a rather sultry reputation— 
one can almost imagine them being smuggled across the channel from 
France in a leaking rowing boat and peddled in the dark alleys of 
Victorian London at two in the morning. 

Whatever use you make of the GIF format—illicitly scanned Robert 
Bateman elevator music for your walls or the naughty etchings of the 
1990s—the ubiquitous nature of GIF files makes the GIF format a 
workable choice if you’ll be importing or exporting pictures in your 
applications. An increasing range of software is appearing with GIF 
support. In a sense, it became everyone’s second favorite PC image 
file format, with no consensus for first place. 

The GIF format can support up to 8 bits of color—for a total of 256 
colors—which makes it suitable for storing dithered photorealistic 
images. Its lack of true color support is one of its fundamental 
limitations in some circles. 



But there is a catch 



The image compression algorithm used by GIF files is called LZW—it 
will be discussed in detail in a moment. At the time GIF was created, 






CompuServe appears to have assumed that LZW was a public-domain 
entity—at least, there’s no indication that they did a patent search to 
find out whether LZW was owned by anyone. CompuServe announced 
the GIF format in 1987 with the following grant of rights to 
developers: 

While this document is copyrighted, the information contained 
within is made available for use in computer software without 
royalties or licensing restrictions. 

As it happens, CompuServe didn’t actually have these rights to 
grant—LZW is a patented entity that is currently owned by the Unisys 
Corporation. There are probably nastier parties that could have turned 
out to own the patent—the Russian Mafia, for example—but few of us 
will ever encounter them outside Frontline. 

Unisys is a fairly ancient mainframe computer manufacturer—they do 
bank terminals, point-of-sale hardware, and such—and one of their 
major enterprises is generating revenue through patents. They hold 
hundreds of them. In the case of the LZW patent, Unisys actually 
acquired it in 1985. They didn’t make much noise about it until 
December of 1994, however, leaving sufficient time for GIF to be 
widely adopted as a graphic file format. 

At the end of 1994, Unisys announced that it would be demanding 
royalties from any developer who created for-profit software that can 
read or write graphic files using LZW compression—for practical 
purposes, this includes GIF and some TIFF files. In addition to having 
to pay Unisys for each copy of their software sold, developers were 
required to undertake additional accounting on behalf of Unisys, to 
display Unisys’ patent notice in their applications, and so on. 

This situation, known informally as a “submarine patent”—it stays 
submerged until it can surface and inflict the greatest damage—is 
actually borderline legal in most countries. It might well be challenged 
in court, but as most of the developers who investigated the possibility 
discovered at the time, Unisys has much deeper pockets than the 
software developers they targeted. 





For its part, CompuServe not only didn’t attempt to defend its 
developers—at one time, it appears to have tried to license the rights 
to certain aspects of the LZW patent from Unisys and sublicense them 
to developers at a higher cost. Unisys claims that CompuServe was 
made aware of the LZW patent in mid-1993 but chose not to tell 
anyone for about a year and a half. 

The results of all this flummery as it pertains to the applications you 
might develop based on the libraries in this chapter are as follows: 

© If you make any money at all by selling your software, Unisys will 
want a cut. It might not be a particularly large cut, but you’ll be on 
the hook to Unisys for the life of their patent. Note that Unisys 
has explicitly exempted not-for-profit freeware applications from 
paying its royalties. 

© As of this writing, Unisys will demand higher royalties if your 
application supports both GIF and LZW TIFF files. The latter will 
be discussed later in this book. 

@ If your software becomes part of a larger product—for example, if 
it’s bundled with a more expensive hardware package—Unisys 
might decide it’s entitled to royalties based on the retail price of 
the larger package. 

© You should probably avoid dealing with CompuServe in trying to 
resolve the GIF royalty issue. As I write this, CompuServe has a 
“GIF Developer’s Program” that costs somewhat more than 
dealing with Unisys directly. 

The best thing you can do with GIF is to stop reading this chapter 
right about here and skip along to the one that deals with PNG files. 
The PNG format was created as a replacement for GIF. It uses an 
unencumbered compression algorithm and transcends a number of the 
limitations of GIF. Among other things, PNG files will typically be 
somewhat smaller than GIF files of the same image. 

If you do have a pressing need to use GIF, you should consult a patent 
and trademark attorney before you release a commercial or shareware 
application that implements it. Have them negotiate a royalty 
agreement with Unisys and advise you of the consequences of doing 
so. Some of the fine print in the “standard” Unisys license agreement 





is pretty ferocious, and the terms seem to vary with Unisys’ 
assessment of what the market will bear. As of this writing, the party 
to contact at Unisys is Mark Starr, Unisys’s corporate council. He can 
be reached at Unisys Corporation, P.O. Box 500, Blue Bell, PA 
19424-0001, or by telephone at 213-986-4411. You can also send 
him a fax at 1-213-986-5721. 


GIF for the fearless 


One of the attractions of the GIF format is that it embodies a sensible 
expansion path built into it. While it serves as a useful way to store 
simple pictures, it can be expanded to apply it to more complex tasks. 
As was touched on earlier, it also implements LZW string-table 
compression as its primary image storage medium. While this probably 
sounds like Martianspeak at the moment—and might still do so by the 
end of this chapter—it means that, all other things being equal, an 
image stored in a GIF file will always take up less disk space than it 
would stored in many other formats. 

Figure 3-1 illustrates a GIF file. In fact, this is one that I scanned—it’s 
not exactly representative of a typical GIF file. The publisher would no 
doubt frown on my including one that is. Note that, while the subjects 
of the picture are women, they do appear to be wearing clothes, 
something that is rarely seen to this extent in contemporary GIF 
images. 

The GIF format has been through one level of revision as of this 
writing. The original specification was released in 1987 and is referred 
to as GIF 87a. The more recent one, released two years later, is called 
GIF 89a. The latter specification is backwards compatible, but it adds 
a number of “extension block” definitions. These will be discussed 
presently. 

At the time of the great Unisys LZW debacle discussed earlier, 
CompuServe was making noises about something called GIF 95a, 
which would have included support for 24-bit true color images. While 
you might still hear faint echoes of this, the GIF 95a project was 
officially drowned at birth at the end of 1994—perhaps on the 





Figure 3-1 



An example GIF file, if a rather unusual one. No topless babes or lawyers 
are to be seen. 

assumption that few developers were likely to trust CompuServe again 
for the foreseeable future. 

A GIF file can hold images with up to 256 distinct colors, drawn from 
a palette of about 16 million. GIF images can support pictures in any 
dimensions you like—and have enough memory to work with— 
although they most often turn up in sizes that match the standard 
VGA and super-VGA screen dimensions. In many cases you’ll find that 
smaller images have been padded out to these dimensions, as was 
noted previously. 

The commonly encountered image dimensions are: 

320 by 200 pixels 
640 by 400 pixels 
640 by 480 pixels 
>* 800 by 600 pixels 
1024 by 768 pixels 





These values probably won’t mean a lot to whatever Windows 
applications you write, in that a window can be any size you like. 

GIF files are also a common element in World Wide Web pages—very 
small GIF files are used as decorations, bullets, borders, bars and other 
incidental graphics. One of the things that endears GIF files to Web 
page designers is that they can be transparent—the control block 
facility of the GIF format allows that one color in an image be declared 
transparent, such that, when a GIF file is painted over an existing 
image, the background will show through in areas that are of the 
transparent color. The mechanism for defining transparency will be 
touched on later in this chapter. 

In fact, GIF files can store a variety of information about their images 
and instructions about how they should be displayed. They can also be 
used to store application-specific information about GIF files, allowing 
them to be adapted for use with complex software. You can store 
multiple images in a single GIF file. 

The most notable element of the GIF standard is the way images in a 
GIF file are compressed: the LZW string-table compression algorithm 
that was mentioned earlier. This makes GIF files awkward to deal with 
in many respects, but it also means that GIF files achieve much better 
compression than do many other image file formats. 

The catch in using LZW compression is that it requires a lot of code 
and a lot of memory and it’s traditionally quite a bit slower than the 
sort of simple run-length compression described in chapter 1. The GIF 
file decoder to be discussed in this chapter has been heavily optimized 
to make it run quickly, but GIF decoding still takes its time. 

The pixel structure of GIF files, while not quite as Windows would 
have it, is arguably easier to transform into device-independent bitmap 
pixels than are some of the other formats discussed in this book. 

A simple GIF file—one with a single image and no optional 
accessories—consists of a header, an image block, and a terminator 
block. The notion of blocks is fairly important to GIF files. The objects 
in a GIF file are not constrained to exist at the same places relative to 
the start of the file, but only relative to each other. 








Let’s begin by looking at the GIF header structure. You can always 
find one of these at the start of a GIF file. It can be seen as a data 
object that looks like this: 

typedef struct { 

char sig[6] ; 

unsigned short int screenwidth,screendepth; 
unsigned char flags,background,aspect; 

} GIFHEADER; 

The sig element in a GIFHEADER object will hold one of two 6-byte 
strings—either “GIF87a” or “GIF89a”—depending upon the revision 
level of the file. A GIF reader should only use the first 3 bytes to 
determine whether the file it’s looking at is an authentic GIF file. In 
theory, a properly written GIF 87a reader would be able to deal with 
the basic image blocks in a newer GIF 89a file—the new features in the 
GIF 89a revision of the specification have to do largely with extension 
blocks. 

It’s worth keeping in mind that some GIF files still use the GIF 87a 
specification. While potentially useful, the extra extension block 
facilities of the GIF 89a specification haven’t really found wide 
application as yet unless you’re creating Web pages. Most GIF files 
only need one picture. 

The screenwidth and screendepth elements of a GIFHEADER define 
the dimensions of the screen that was used to initially view the GIF file 
being created. This is not necessarily the same as the dimensions of 
the image itself. In a GIF file having multiple images, this information 
might be useful in choosing an optimum screen mode to view all the 
pictures in. In practice, it’s a bit meaningless under Windows, which is 
effectively modeless. 

Note that many GIF readers check these values even if they don’t use 
them. They should be sensible. The most obvious thing to use for 
these numbers would be the dimensions of the first picture in a GIF 
file. The GIF reader to be discussed in this chapter will ignore the 
screen dimensions of the files it reads. 





The flags element of a GIFHEADER contains a number of useful 
values. To begin with, you should test flags & 0x80. If this is true, the 
GIFHEADER object will be followed by a color map; that is, by a 
palette lookup table. The number of bits of color it represents can be 
calculated as (flags & 0x0007) + 1 . There are 3 bytes for each color, 
ordered red, green, blue. 

If flags & 0x08 is true, the color palette will be sorted with the most 
important colors first. This won’t really mean all that much to a 
Windows application, which deals with a superfluity of color in other 
ways, as was discussed in chapter 2. This flag is rarely used. 

Finally (1 << ((flags >> 4) + 1) represents the number of colors in 
the original image from which the GIF file was derived. This might not 
be the same as the number of colors in the actual picture. Once again, 
this information is rarely of any practical use. 

The latter two items are unique to the GIF 89a specification. These 
bits are set low in GIF 87a files. Because many images in the GIF 
format still use the 87a specification, it’s probably not a good idea to 
write a GIF decoder that anticipates being able to use the sort flag or 
the source color palette size fields if you anticipate its being presented 
with a variety of GIF files from the usual public-domain sources. 

The background field contains the color number of the background of 
the images in the file. On a VGA card driven from DOS, this value can 
be used to set the background and border of a displayed picture to a 
value determined by the image, rather than arbitrarily to black or to 
whatever happens to be the first color in the palette. This does not 
have any direct parallel under Windows, although you could modify the 
VIEWER program to fill the unused portion of its window with this 
color, rather than with the brick pattern, if you wanted to be 
exceedingly thorough. 

The aspect field is unique to GIF 89a files. It’s always zero in GIF 87a 
files. This specifies the aspect ratio of the pixels in the image. If this 
field isn’t zero, the aspect ratio of the pixels in the image is (aspect + 
15) / 64. This is another of those things that doesn’t mean a great deal 
under Windows, as Windows doesn’t really give you any way to 
change the shape of its pixels. 







Note that, because this field was constrained to be zero under GIF 
87a, many older GIF readers will decide they have a corrupted file if 
they encounter a GIF 89a file that uses this field. 

If the flags field of the GIF header indicates that a color map is 
available, it comes next. This is called a global color map. It should be 
regarded as being a default set of colors that might be overridden by 
specific images in the file being read. In practice, most simple GIF 
files—GIF files with one image and no extensions—have a global color 
map as their only set of color definitions. 

As the maximum number of colors in a GIF file is 256 and the number 
bytes of an RGB color is 3, the maximum amount of memory needed 
to hold the palette information of a GIF file will be 768 bytes. If a 
global color map is available, you can work out the number of bytes it 
encompasses based on the number of bits of color, as indicated by the 
flags field of the header, and read these bytes into a buffer. 

Note that, unlike as with color definitions under Windows, the color 
entries in a GIF file’s palette appear in the order red, green, blue. 

The next byte to be read from a GIF file once the header and the 
optional global color map has been dealt with will be the beginning of 
the first block. A block can be one of three things, as indicated by the 
byte that introduces it. If the byte is a comma, the block contains an 
image. If it’s an exclamation point, it’s an extension. If it’s a 
semicolon, the block is a terminator, indicating that all the blocks in 
the file have been read and it’s time for the decoding software to give 
up and go home. In a simple GIF file, you would encounter one image 
block followed by one terminator block. 

A GIF image block consists of a secondary header for the image 
followed by the compressed image data itself. This is what the header 
looks like: 

typedef struct { 

unsigned short int left,top,width,depth; 
unsigned char flags; 

} GIFIMAGEBLOCK; 








If you encounter a comma as the introduction to an image block, you 
should find one of these immediately thereafter. 

The left and top elements in a GIFIMAGEBLOCK object specify the 
coordinates at which the upper-left corner of the displayed image 
should appear relative to the upper-left corner of your screen or 
display window. These values are ignored by the VIEWER application 
discussed in chapter 2. You might want to do something with them if 
you create a more elaborate GIF viewer. The width and depth values 
represent the actual image dimensions for the image about to be 
decoded. 

The flags element behaves more or less like the flag set in a global 
header, with one important difference. The GIF 89a-specific fields of 
the global header don’t appear in this set of flags, but if flags & 0x40 
is true, the lines in the file will have been stored interlaced. This means 
that they will not emerge from the file in the order you might expect 
unless you usually count on your toes and happen to have been born a 
centipede. 

An interlaced GIF file splits its image into four frames. The first frame 
consist of every eighth line of the source image, beginning with line 
zero. The second frame consists of every eighth line, beginning with line 
four. The third frame consists of every fourth line, beginning with 
line two. The final frame consist of every second line, beginning 
with line one. 

The usefulness of interlaced pictures is that you can get a reasonable 
idea of what a whole GIF image looks like when only a quarter of it 
has been decoded. This was more relevant back when computers are a 
lot slower than they are now, and it still has applications in allowing 
GIF files to be viewed as they’re downloaded, something that seems to 
enjoy a renaissance of sorts every so often. Interlaced GIF files are 
another aspect of the GIF specification that is an active part of Web 
page design. Perhaps not surprisingly, this attribute of GIF files 
complicates GIF decoders and some applications in general to a 
considerable degree. 

The byte following a GIFIMAGEBLOCK header will be the ‘initial code 
size for the compressed image data, something that will be discussed 









in greater detail in a moment. The next byte along will be the first 
byte of the first field of the compressed picture. Compressed GIF data 
is stored in fields of up to 255 bytes. Each field consists of a byte to 
indicate its length and then the field data itself. The last field will have 
a length of zero. 


1 GSF file compression 

The run-length compression discussed in chapter 1 essentially worked 
by looking for two fixed conditions in an image file and replacing them 
with tokens. In the case of a run of bytes field, the token could 
represent much less data than it replaced, and as such run-length 
compressed files with potential run of bytes fields in them can get 
smaller. 

String-table or LZW compression works by letting the image data 
define the tokens to be used. In a sense, it’s run-length compression in 
which the compression algorithm defines itself based on the specific 
image it’s asked to compress. 

Any type of information can be compressed this way. The PKZIP and 
LHARC file compression programs apply much the same approach to 
compression to any sort of disk files. As an aside, this might help to 
explain why GIF files don’t compress when you ZIP them. Applying 
LZW compression to data that has already been compressed doesn’t 
make it any smaller. 

In GIF files, image data is always compressed based on one byte per 
pixel. This might seem a bit wasteful, inasmuch as a picture with 16 
colors would only use 4 bits out of the 8 in each byte. In fact, as you’ll 
see in a moment, LZW compression doesn’t actually compress the 
unused bits in a byte, and as such ignores this superfluous real estate. 

It’s a lot easier to understand LZW compression if you begin with the 
decompression process. This example will look at the process of 
unpacking a GIF file. It assumes that the GIFIMAGEBLOCK header 
and the initial code size byte have been read and that the data being 
looked at is the beginning of a block of compressed image 
information. 





Chapter 3 




A function to decode LZW-compressed data works with three objects, 
to wit, a code stream , a code table and a character stream. The code 
stream is the data being read from the compressed file. The character 
stream is the uncompressed data, which will go to the data portion of 
the device-independent bitmap created to hold the contents of a GIF 
file when it’s unpacked. The code table consists of a stack of entries in 
which codes from the file will be associated with strings of data. In a 
GIF file, the code table has 4096 entries. The image data in a GIF file 
can be compressed with up to 12 bits per code—2 raised to the power 
of 12 is 4096. 

Note that these 12 bits refer to the maximum number of bits that the 
LZW compression function that originally created the GIF file in 
question is allowed to squeeze into a code for maximum compression 
efficiency. This is not the same as the number of bits of color the file 
can contain. Compression will always begin by assuming that there are 
no fewer than the number of bits of color in the picture being 
compressed, but it’s allowed to increase the bit count to a maximum of 
12 bits. 

The effectiveness of string-table compression improves with the 
maximum number of bits allowed in a code. In some cases, you’d 
achieve better compression with a 14-bit maximum code size, rather 
than a 12-bit one. However, a 14-bit LZW compression function would 
require a string table with 16,384 entries. For practical purposes, each 
entry consists of two integers and a byte, for a total of 5 bytes per 
entry. This would make the table 81,920 bytes long. Not only is this a 
substantial amount of memory to tie up in itself, but it’s too large for 
16-bit applications to address using far pointers. 

Having 12 bits as the maximum code size is a reasonable compromise 
between file compression and the complexity of the code required to 
handle GIF files. A GIF decoder is a pretty nasty function as it stands. 
It’s also fairly slow as file decompression functions go, and increasing 
the maximum code size would make it slower still. 

There are a number of other bits of information that are important to 
keep in mind before you start trying to fathom GIF decoding. 







Specifically, there are several special codes that are defined before the 
decoding process starts working. These are as follows: 

#define CODESIZE (1 « bits_per_pixel) 

#define CLEAR_CODE CODESIZE 

#define END_OF_IMAGE (CLEAR_CODE + 1) 

#define FREE_CODE (CLEAR_CODE + 2) 

Before the decoding process gets under way, the string table must be 
partially initialized. Specifically, the first CODESIZE entries must be 
initialized with their positions in the table. Entry zero will contain zero, 
entry one will contain one, and so on. 

For an 8-bit picture—that is, one with 256 colors—entries 0 through 
255 will be initialized. Code 256 is the clear code, and code 257 is 
the end-of-image code. Code 258 is the first free code in the table. If 
a GIF decoder encounters CLEAR_CODE in the code stream, it will 
immediately reinitialize its string table. If it encounters 
END_OF_IMAGE in the code stream, it will shut down and go home. 

The use of CLEAR_CODE might not be entirely clear. As an image is 
compressed, the string table of the compression function gradually 
gets full of strings. For as long as there are fewer than 4096 strings in 
it, it’s free to use the existing strings should it find duplicates of them 
in the data it’s compressing and to add new ones to it should it 
discover strings it has not previously encountered. If the string table 
becomes filled, it deals with this condition by throwing away all its 
strings and starting over. Ffowever, it must signal this event so that, 
when the file is decoded, the decoding function will know to throw 
away its string table at the same time. The signal for this is 
CLEAR_CODE. 

Figure 3-2 illustrates what happens as a GIF file is uncompressed. 

Unlike as with many graphic formats, a GIF encoder doesn’t really 
care about the ends of individual scan lines. It regards the entire image 
as a block of data and compresses it in one pass. A GIF decoder will 
reconstruct images one line at a time because this is how image data is 
generally used. However, this is a bit of fiction that GIF decoders 
enact for the benefit of whatever software will use the image data. As 
with a GIF encoder, a decoder just sees a long stream of bytes. 
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This is a very simplified diagram of a GIF decoder. In 
some states, this process requires parental approval if it’s 
to be used by persons under the age of 18. 















Compressing a GIF image works in precisely the opposite way to 
uncompressing one. The code and character streams are reversed. 

It’s important to note that string-table compression is bit oriented. 

This accounts for its effectiveness—it’s not constrained to deal with 
strings in 8-bit chunks, as simple run-length compression is. Bitmaps 
are, after all, effectively strings of bits, even if we choose to store 
them in bytes. However, because information in a computer is stored 
in bytes, a fair bit of cheating has to go on in a GIF decoder to deal 
with individual bits in this form. The result is that unpacking an LZW 
compressing image is fairly processor intensive, and it takes awhile. 

The GIF specification has images stored with one byte per pixel no 
matter how many bits of color each pixel contains. There’s no wasted 
data inherent in doing so, however, because string-table compression 
compresses bits, not bytes. If each 1-byte pixel only contains 4 bits of 
meaningful color information, only 4 bits will be packed. 

This means that a line of image information from a monochrome GIF 
file the size of a standard VGA screen would be 640 bytes wide, rather 
than the 80 bytes that would actually be written to the screen buffer. 
Each byte would hold the number 0 or 1, with color 0 being black and 
color 1 being white. Software that wanted to read a monochrome GIF 
file would probably have to convert this information to a more 
practical single-plane monochrome image—it represents a fairly 
sloppy way to store uncompressed black-and-white pictures. 

Only images with more than 4 bits of color will emerge from a GIF 
decoder in a format that is immediately compatible with a Windows 
device-independent bitmap. Pictures with less color depth will require 
some manipulation. Specifically, a GIF image with 4 bits of color must 
be manipulated such that every two GIF pixels are combined into a 
single Windows chunky pixel, with one pixel in the upper 4 bits and 
the other in the lower 4 bits. Monochrome images must be converted 
from one byte per pixel into one bit per pixel. 

Converting a 4-bit GIF file into an appropriate format for Windows to 
work with can be handled through the PutChunkyPixel macro 
introduced in chapter 2. 






The following code shows how you’d convert a black-and-white GIF 
image line into a suitable Windows bitmap line. 

int i,j; 

for(i=0;i<fi->width;++i) { 

if(linebuffer[i]) 

extrabuffer [i»3] ! = 

masktable[i & 0x0007]; 

else 

extrabuffer[i>>3] &= 

~masktable[i & 0x0007]; 

} 

This bit of code will require another digression to fully explain. The 
use of the masktable object hasn’t been dealt with as yet, although it 
did turn up in the WINBIT source code in chapter 2. It’s a powerful 
tool for working with bit fields. 

A digression about bit fields 

In any real-world application, uncompressed monochrome images will 
be stored as bit fields; that is, with one bit per pixel. In fact, these bits 
will be contained in bytes, as this is how computers like to keep track 
of them. The processor in a PC has all sorts of instructions for dealing 
with bytes—individual bits are somewhat trickier. The masktable 
object is used to read and write individual bits in a line of bytes. 

In this example, p will be a single line in a monochrome image, such 
as one line of a GIF file after it has been through the foregoing 
function to convert it to monochrome. The pixel to be dealt with will 
be x pixels in from the left edge of the line. 

Inasmuch as there are 8 bits in a byte, the byte that contains pixel x 
will be p[x / 8]. You can divide by even powers of two much more 
quickly by using bit shifts. The byte can also be located as p[x >> 3]. 
Dividing by eight can be seen as discarding the 3 low-order bits of the 
number that specifies the location of the pixel x. 

To determine whether a particular pixel is on or off in a byte, you 
would AND the byte with a mask that represents the position of the 
pixel. A mask is a byte with only one bit set. You can calculate the 
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mask to determine the position of the pixel at x as 0x80 >> (x & 7). 
The value 0x80 is a byte with its high-order bit set and all its other bits 
off. As such, if p points to the line, you would test to see if pixel x is 
set in the first plane by seeing if (p[x >> 3] & (0x80 >> (x & 7))) is 
nonzero. 

Calculating 0x80 >> (x & 7) is time-consuming if you’ll be doing it a 
lot. You can cut the time it takes to work out each mask by observing 
that there are only eight possible results from this calculation. They 
can be stored in a table. 

char masktable[8]= { 0x80,0x40,0x20,0x10,0x08,0x04,0x02,0x01 }; 

With this table available, the calculation of a bit mask can be reduced 
to masktable[x & 7], 

Bitwise manipulation with masktable can be used to test and 
manipulate bits in a bit field. We’ve seen what’s involved in testing 
bits. Much the same approach is used when you want to modify the 
individual bits in a string of bytes. 

The easiest bitwise manipulation is setting a bit on. It’s done by ORing 
a mask with one byte of a bit field. This is how you’d set pixel x in line 
P = 


p[x >> 3] != masktable[x & 7]; 

To turn a bit off, you must AND the appropriate byte with the inverse 
of the mask that you would have used to set the bit on by ORing it. 
This has the effect of leaving all the existing bits unaffected save for 
the one that you wanted to turn off, which will be masked. It’s done 
like this: 

p[x >> 3] &= -masktable[x & 7]; 

Finally, to flip a bit—that is, to invert its state—you can XOR a mask 
with the bit field, like this: 


p[x » 3] A = masktable[x & 7]; 









You’ll find code that uses masktable like this throughout the next few 
chapters. Several of the image file formats in this book handle their 
images as bit planes rather than with each pixel stored as a byte, or a 
portion of one. 


The idea of GIF extension blocks was mentioned earlier in this 
chapter. It’s worth noting that you can wholly ignore extension blocks 
if you’re only interested in the primary images in GIF files. One of the 
characteristics of all GIF extension blocks is that they can be skipped 
without an application even having to know what they are. 

More sophisticated applications of GIF files often involve the use of 
extension blocks. The one that you’re most likely to encounter is that 
of transparency for GIF files used by Web pages. While the concept of 
extension blocks is expandable and allows you to adapt the GIF format 
for your own uses to some extent, the existing definitions for extension 
blocks offer quite a bit of scope as they stand. Using them, you can 
create multiple-cell animations in a single GIF file, interactive GIF files, 
GIF files with elements that appear and disappear, and so on. 

The code in this chapter will not deal with all the possibilities of GIF 
file extension blocks. The VIEWER application will display single 
image GIF files, but it’s not a “fully compliant” GIF viewer; that is, it 
will not deal with all the permutations of GIF files with extension 
blocks. You might want to expand it to do so if you’re interested in 
complex GIF files. 

The Bookware applications on the companion CD-ROM for this book 
include GIF Construction Set, which is a fully compliant GIF viewer. It 
also knows how to assemble complex GIF files that include multiple 
images and extension blocks. 

It’s probably worth noting that few GIF files actually make use of 
extension blocks at all, and fewer still do anything with them beyond 
storing text messages in them. 
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An extension block begins with an exclamation point. At present, 
there are four types of extension blocks defined: 

Graphic control extension —This block lets you define how an 
image will be displayed, whether someone watching it can 
interrupt its display, how long it will be displayed for, and so on. 
It also stores transparency information, as touched on 
previously. 

Comment extension —This block lets you add text comments to 
an image file. 

Plain text extension —This block contains text that is to be 
positioned and displayed over a graphic screen. 

>■ Application extension —This block can contain anything you 
like to customize the GIF format for your specific applications. If 
you’re creating GIF files for a World Wide Web page, you might 
encounter application blocks as Netscape looping definition. 

GIF Construction Set pretends that looping blocks are a special 
sort of GIF extension, but they’re really just application blocks. 

Obviously, none of these blocks will do anything at all if the GIF file 
that contains them is being read by an application that ignores them. 

The VIEWER application does not respond to GIF extension blocks—it 
just fetches the first image in a GIF file and displays it. You can see 
how a complex GIF file is structured with the Graphic Workshop for 
Windows application on the companion CD-ROM for this book. Select 
the GIF file, click on the Get Info button and then on Details. Figure 
3-3 illustrates the details dialog for a GIF file without any extension 
blocks and for one with several. 

One of the most common applications for extension blocks, when 
they turn up at all, is to attach a copyright notice, credits, or 
disclaimers to an image file. Considering that most GIF files contain 
nudes, the latter is most often the case. The extension blocks 
illustrated in Fig. 3-3 were put there by a bulletin board. 

An extension block is structured as an exclamation point to indicate 
the existence of an extension followed by a code to tell the reading 
software what sort of extension it has encountered. By default, 
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Figure 3-3 




extension blocks are structured such that you can work your way 
around a block of unknown characteristics. 

The simplest sort of GIF extension block is a comment. If the next 
byte after the exclamation point is OFEH, the extension is a comment 
block. A comment block consists of nothing but raw ASCII text. The 
text is stored in multiple data subblocks. A data subblock is defined as 
a byte to hold the length of the block followed by as many bytes as the 
length byte defined. A comment block can contain as many data 
subblocks as it requires to hold its text. As a byte can only hold 
numbers up to 255, larger amounts of text must be split up into 
multiple data subblocks. A comment extension is defined as ending 
when the first data subblock with zero bytes in it is encountered. 

You can read the text out of a comment extension block as follows. 
This example assumes that the OFEH byte has just been read, that the 
file being read from has been opened with the file pointer fp, and that 
p is a buffer to store the text in. This code would require some 
enhancement to use in a real-world application—for one thing, there’s 


Details 


SllSCREEN DESCRIPTOR 


LIPS.GIF 

GIF87a 

Screen dimensions: 
Screen hits: 
Background colour: 
Global palette: 

IMAGE BLOCK 


Image dimensions: 
Image bits: 

Local palette: 
Interlaced: 


640 by 400 
4 

NO 

NO 



The details for a single image GIF file (a) and for a complex GIF file with 
multiple images and extension blocks (b). 



































A plain text block—an extension to hold text that will be overlayed 
above a graphic—is identified by the byte 01H after the exclamation 
point that identifies the start of the extension. Following the 01H byte 
is this data structure: 

typedef struct { 

char blocksize; 

unsigned short int left,top; 

unsigned short int gridwidth,gridheight; 

char cellwidth, cellheight; 

char forecolor,backcolor; 

} PLAINTEXT; 


The left and top elements of this structure represent the starting 
position for the displayed text. The gridwidth and gridheight fields 
specify the distance in pixels from one character to the next for the 
text to be drawn. The cellwidth and cellheight fields specify the actual 
dimensions in pixels of the characters to be used. Note that a GIF file 
itself does not provide a font to draw the text in—it assumes that a 
suitable font will be available to the viewer that interprets it. 

You could store fonts as an application extension, to be discussed 
momentarily. 

The forecolor and backcolor fields are the foreground and 
background color map indices, respectively, to draw the text in. 

Following this data structure is the text itself. It’s stored as data 
subblocks, as previously described. 

Any GIF file that has more than one image block in it will also contain 
control block extensions so that a viewer that encounters the pictures 
will know how they’re to be displayed. The byte that identifies a 
graphic control block extension is 0F9H. Immediately after this byte, 
you’ll find the following data structure: 

typedef struct { 

char blocksize; 
char flags; 

unsigned short int delay; 
char transparent_color; 
char terminator; 

} CONTROLBLOCK; 
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The blocksize field always contains the value 04H. 

If (controlblock->flags and 0x01) is true, 

controlblock->transparent_color will contain a valid transparent 
color index. This color, when used in displaying the contents of the 
following image block, should be regarded as not being there and 
should not be written to the screen. Anything below it should appear 
to show through the new graphic. 

If (controlblock->flags and 0x02) is true, the viewing program that 
displays the following image block should wait for user input; that is, 
for a keypress to allow the viewer to continue on to the next image in 
the file. If (controlblock->delay) is greater than zero and user input is 
expected, the viewer should wait for the number of hundredths of a 
second specified in the delay field or for a keypress, whichever comes 
first. If the delay value is greater than zero but user input is not 
specified, the viewer should wait for the number of hundredths of a 
second specified but ignore anything that happens at the keyboard. 

The value provided by ((controlblock->flags >> 2) & 0x0007) 
represents the method by which the GIF viewer should remove the 
graphic in the next image block from the screen when it’s time to 
dispose of it. The choices are as follows: 

0 —Do nothing. 

1— Leave it where it is. 

2— Restore the area beneath it to the background color. 

3— Restore the area beneath it to the previous graphic. 

It’s quite acceptable for a GIF decoder to ignore those elements in a 
control block extension that it doesn’t care about—or to ignore the 
whole extension. 

Application blocks constitute the final type of GIF file extension block. 
By definition, these are specific to the application that creates them. 
Unless your GIF file viewer is confronted with an application extension 
that has been put there by your software, you should probably ignore 
the contents of the block. 





The byte that identifies an application extension is OFFH. The 
following data structure comes after the byte: 

typedef struct { 

char blocksize; 
char applstring[8]; 
char authentication[3]; 

} APPLICATION; 

The applstring field is an 8-byte string that identifies the software that 
should know what to do with the application block in question. The 
authentication field should contain 3 bytes that are based on the 
contents of the applstring field run through an algorithm of your 
choice. For example, you could perform a checksum of the applstring 
field, possibly XORing a few bits in the process, and store the results 
in the authentication field. This will allow a GIF viewer that uses 
application extension blocks to store proprietary information the 
opportunity to make sure that it’s looking at one of its own application 
extensions and not merely one that has the same applstring field. 

Following this structure is the actual data in the extension, stored in 
data subblocks, as in previous extension blocks. 

M Macintosh GIF files 


The GIF format was clearly designed for use on PC-based systems, but 
the popularity of GIF files and all the unclothed babes they contain 
quickly migrated to other platforms, including Macintosh systems. Mac 
people are supposed to be above this sort of thing, but GIF readers 
and GIF creation software is available for the Macintosh nonetheless. 

A GIF file created by a Macintosh system should be identical to one 
created on a PC. In practical terms, this isn’t always the case, as 
Macintosh GIF files might be preceded by a rather troublesome header. 
A GIF reader should know about these headers and be equipped to 
sneak past them. 

To understand Macintosh GIF files, you might have to plunge into the 
turgid and shark-infested waters of the Macintosh for a while and get 
into the following digression about computers from California. If you 






close your eyes, you can almost hear the BMWs passing in the 
distance and smell the sweet aroma of burning marijuana and Gucci 
shoes. 

The designers of the Macintosh gave it a lot of weird elements, but 
none was quite so weird as its disk structure. Because the original 
Macintosh was required to run with very little memory—about half of 
which was occupied by its enormous operating system—the whole 
affair was structured to allow application code and data to be paged 
on and off disk as readily as possible. A typical Macintosh application 
is structured as numerous small blocks of code, called resources , that 
can be read from the disk as they’re needed and subsequently 
discarded. While this makes a Mac application running in confined 
quarters very slow, it does allow applications that require more 
memory than a Mac is prepared to give them to crawl along, rather 
than having them stop all together. 

Windows and Warp applications are structured the same way, of 
course, but a Mac has been designed around the concept of resources 
from the ground up. To facilitate getting at these blocks of code and 
data in an orderly manner, Macintosh disk files are structured in two 
forks. In effect, each Macintosh file is really two files, held together 
with virtual bungee cords. The resource fork is where all the 
structured code and data blocks live. The data fork is where any 
nonstructured data would go. 

Different sorts of Macintosh files make use of these forks in 
different ways. For example, a Macintosh GIF reader application 
would be a collection of resources—code resources, menu resources, 
font resources, cursor resources, and possibly quite a few 
proprietary resources intelligible only to the software itself. It would have a 
large resource fork. Because there is typically little or nothing in an 
application that cannot be defined as a resource, an application 
usually has an empty data fork. 

A GIF image file, on the other hand, would have no resources. All 
picture information is just raw data and would live in the data fork. As 
such, its resource fork would be empty. 







The original intent in designing the Macintosh, of course, was that the 
entire sentient universe would stand before it in awe, want a Mac more 
than life itself, and forsake anything else with a microprocessor in it, 
including programmable toasters and most imported cars. Had this 
come to pass, the weird file structure of the Mac wouldn’t have 
mattered, as it would have been universally weird, and everyone would 
have gotten used to it. 

Depending upon whose demographics you choose to believe, 
Macintosh systems only account for about 10% of the personal 
computers in use at the moment, with almost all of the others being 
PC systems. There are numerous possible philosophical reasons for 
this, perhaps the most understandable being that few people like to 
run Windows while a man with a gun keeps an eye on them. The one 
that is most easily understood, however, has little to do with 
philosophy. Macintosh systems aren’t very cost effective. Having 
waved its lawyers in the faces of any potential competitors, Apple has 
had relatively little impetus to keep the price of Macintosh hardware 
down where it can be afforded without the application of a second or 
third mortgage to your cat. Rumor of Macintosh clones dance upon 
the fingers of the media as I write this. 

In using GIF files created on a Macintosh, a PC application is 
confronted with a number of specific and somewhat thorny problems. 
Specifically, you’ll have to figure out: 

© How to get the little monsters from the Macintosh on which they 
reside into a format your PC can read. 

@ How to deal with the Macintosh’s two pronged file structure. 

These two issues turn out to be somewhat entwined, and how they’ve 
been solved in the case of the Macintosh GIF files you encounter will 
determine whether the files in question are conventional GIF files or 
slightly mutated Macintosh GIF files. 

There are several ways to get a file from a Macintosh to a PC. If the 
Mac in question is fairly new, it will have the Apple File Exchange 
software included in its operating system. Macs thus equipped can 
read and write PC-formatted high-density floppy disks. As such, GIF 
files can be ported between the two platforms painlessly. 





This is also usually the case for PC and Macintosh computers that are 
part of the same local area network. 

In both these cases, what really happens is that the original Macintosh 
file being copied will be split into two files—the target PC file will 
contain only the data fork contents of the source file, with the 
resource fork being written to a second, usually hidden, file. However, 
because GIF files are all data fork, this will leave a PC application with 
precisely what it’s expecting, and all will be well. 

Moving GIF files back to a Mac environment is somewhat trickier, but 
as this book is about bitmapped graphics for Windows and OS/2—and 
not for Macs—you can safely ignore the issue. 

Things only get complicated if you’re dealing with GIF files that have 
been uploaded from a Macintosh computer to a bulletin board, a dial¬ 
up service, or the Internet. The authors of the first telecommunication 
software for Macintosh systems were confronted with the problem of 
exchanging files comprised of two forks in a universe that seemed to 
have found one fork quite adequate. Specifically, it was necessary to 
preserve the forks of a ported file and to include its Macintosh 
filename, creation data, and a number of other information fields in its 
trip through the wire. 

In uploading Macintosh files to bulletin boards, these early applications 
were confronted with the realization that most bulletin boards were 
running on PC hardware. A bulletin board is essentially a fairly simple 
computer connected to as big a hard drive as possible—mass storage 
has always been a lot more expensive when it was connected to a 
Macintosh. 

In effect, the problem of sending Macintosh files out into a cruel, non- 
Macintosh universe was handled by devising a way to combine them 
into single-fork data structures on the way out of a Mac, then to 
restore them to two-fork files with all the regalia of a Macintosh on 
the way back in. This was handled by combining the two forks into a 
single file with a header preceding them to inform later Macintosh 
systems how the file should be split up. 
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When the header structure was devised, file transfers were handled in 
blocks using the XMODEM protocol, which specified that each block 
would be 128 bytes long, a value dating back to a still earlier set of 
standards. As such, the file header on a ported Macintosh file is 128 
bytes long, too—it serves as a zero’th block when it’s sent, telling a 
receiving Macintosh that it should deal with the subsequent blocks as 
the two forks of a Macintosh file. The header looks like a normal block 
to a PC, which will treat all the ensuing blocks as being part of a single 
inscrutable binary file. 

The header used to export Macintosh files is informally called a 
Macbinary header. It’s a bit of a nonstandard standard, as it’s not an 
official Apple data structure, and it isn’t very well documented. This is 
what it looks like. 

typedef struct { 

char zerobyte; 
char name[64]; 
char type[4]; 
char creator[4]; 
char filler[10]; 
long datafork_size; 
long rsrcfork_size; 
long creation_date; 
long modif_date; 
char filler2[29]; 

} MACBINARY; 

Almost none of this is exactly what it seems to be. 

The zerobyte element of a MACBINARY object should contain zero— 
it’s actually the flag to tell a Macintosh telecommunications package 
that the first block of an incoming file is actually a Macbinary header. 
The name field will contain the original Macintosh name of the file. 
Macintosh filenames can run to as many as 31 characters and are 
allowed to contain spaces, lowercase characters, and quite a few other 
symbols that don’t appear in PC short filenames. Note that this will be 
a Pascal string—the first byte represents its length, and it’s not 
necessarily terminated by a zero byte. 

The type and creator fields of a MACBINARY object will contain the 
original type and creator values of the file as they appeared on a 
Macintosh. A file’s type field tells the Macintosh what it is. Its creator 






field specifies which application it’s to be associated with. On a 
Macintosh, both files and applications have icons—if you were to click 
on a GIF file, its creator field would tell the Macintosh to boot up a 
suitable GIF viewer and then have the viewer load the file you’ve 
clicked on. The type field has much the same function as file 
extensions on a PC do. 

Note that, while all GIF files will have “GIFf” as their types, their 
creator fields will vary, depending upon which of the available 
Macintosh applications actually created them. 

The datafork_size field of a MACBINARY object specifies the number 
of bytes in the data fork of the file in question—sort of. The 
rsrcfork_size field specifies the number of bytes in its resource fork. 
By convention, a Macintosh file packed with a Macbinary header 
always has its data fork first, so unpacking one into two forks involves 
reading the number of bytes defined in datafork_size into the data 
fork and reading the remaining bytes into the resource fork. In a 
MacPaint file, the value of rsrcfork_size will always be zero. 

The phrase “sort of” in the preceding paragraph might have attracted 
your attention. Everything in the foregoing paragraph is correct, but 
only on a Macintosh. For reasons perhaps best ascribed to the general 
perversity of the universe, the Motorola processors upon which 
Macintosh systems are founded have chosen to store their multiple- 
byte objects differently than do the Intel processors that drive PC 
systems. Specifically, integers and long integers will have their byte 
orders reversed on a Macintosh. 

This, of course, also pertains to data objects exported from a 
Macintosh. As such, the fork sizes in a Macbinary header will not be 
correct when they’re read as long integers on a PC. The following is a 
function to deal with this problem: 

long motr2intel(long 1) 

{ 


return(((1 

& 

Oxff000000L) 

>> 

24) + 

( (1 

Sc 

OxOOff0000L) 

>> 

8) + 

( (1 

Sc 

OxOOOOff00L) 

<< 

8) + 

( (1 

Sc 

OxOOOOOOffL) 

<< 

24) ) ; 


} 
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If m is a MACBINARY object, this is the correct size for its data fork 
on a PC system: 

size=motr2intel(m.datafork_size) 


Note that motr2intel will also translate Intel-format long integers back 
into Motorola long integers, as one is the inverse of the other. 

The size of a Macintosh GIF file’s data fork isn’t really important in 
reading one on a PC—having skipped past a Macbinary header, you 
can decode the ensuing GIF file normally and know where the end of 
the file resides. You might, however, want to know how to correctly 
set these fields if you choose to create GIF files that are to be 
downloaded back to a Macintosh system. 

The other Motorola-format long integers in a MACBINARY object that 
you might want to concern yourself with are creation_date and 
modif_date —predictably, the original creation date and most recent 
modification date of the file in question. Not only are these Motorola 
numbers—necessitating a trip through motr2intel if they’re to be read 
on a PC—they’re also based on a wholly different date structure. 

Both Macintosh and PC systems use system clocks that count the 
number of seconds since the dawn of recorded time, or some 
reasonable approximation thereof. For a PC, time began on January 
1, 1980, there having been no PC systems prior to this time. On a 
Macintosh, it began on January 1, 1904. The significance of this latter 
date is less clear—it might have been the first occasion of one 
company suing another over a piece of fruit. 

You can convert a Macintosh date stamp into a PC date stamp by 
subtracting the number of seconds between these two events. The 
number of seconds can be represented as: 

#define MAC 2 PC_DATE 2082830400L 

Under Borland C++, this is how you’d create an ASCII representation 
of a Macintosh file creation date. Once again, this assumes that m is a 
MACBINARY object: 


long t; 
char *p; 










t=motr2intel(m.creation.date); 
p=ctime(&t); 

The object pointed to by p will be a normal C language string defining 
the date and time of the file’s creation. 

If you don’t much care about the Macintosh-specific information in a 
Macintosh GIF file, there’s a quick and nasty way to cope with GIF 
files having a Macbinary header. If a program that reads GIF files 
attempts to read the GIF file header and fails to find the string GIF in 
the first three bytes of the signature, it should check the first byte to 
see if it’s a zero. If it is, the file is probably a GIF file with a Macbinary 
header up front. In this case, a GIF reader should seek 128 bytes into 
the file and have another shot at finding the GIF file header. 

1 The GIFLIB library 

The GIFLIB.CPP file compiles to create GIFLIB16, GIFLIB32, or 
GIFLIBW.DLL, depending upon the platform you want to use it with. 
Its structure will illustrate both how to read and write GIF files and 
how the remaining libraries in this book will be put together. It’s 
illustrated in Fig. 3-4. 

The exported functions in the graphic file format libraries were 
discussed in detail in chapter 2—only three of them do anything 
specific to GIF. They are GetFilelnformation, ReadGraphicFile, and 
WriteGraphicFile. The GetFilelnformation function creates a handle 
to a BITMAPINFOHEADER object and fills it with data—a procedure 
that’s duplicated in ReadGraphicFile, except that the latter creates a 
complete device-independent bitmap. 

The ReadGraphicFile function illustrates the essential logic required 
to parse a GIF file’s header and blocks. It begins by opening the file 
and reading its contents into a GIFHEADER object. If the first three 
bytes of the GIFFIEADER aren’t GIF, it seeks 128 bytes into the file 
and tries again—this deals with GIF files that have Macbinary headers. 
If a GIF header doesn’t turn up, it gives up and qoes home, returning 
a NULL handle. 
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/ 


GIF Library 

Copyright (c) 1995 Alchemy Mindworks Inc. 


*/ 

#include <windows.h> 
#include <stdio.h> 
#include <string.h> 
#include <stdlib.h> 
#include "winbit.h" 

HANDLE hlnst; 



#define 

WRITE_GIF89 

TRUE 

#define 

GIFCOMMENT 

\ 

#define 

"This GIF file was created by the example GIF\: 
"application from Steve Rimmer's book WindowsV 
"and OS/2 Bitmapped Graphics, published by\r"\ 

"Winderest/McGraw Hill.\r\r"\ 

"Use no hooks." 

NO_CODE -1 

#define 

GIFLARGESTCODE 

4095 /* largest possible code */ 

#define 

GIFTABLESIZE 

5003 /* table dimensions */ 

#define 

GIFSIG87 

"GIF87a" 

#define 

GIFSIG89 

"GIF89a" 

#define 

GIFVERSION 

59 

#define 

GIF SUBVERSION 

GIFVERSION+2 

#define 

GIFREVISION 

GIFSUBVERSION+1 

typedef struct { 
char sig[6]; 
unsigned short int 

screenwidth,screendepth; 


unsigned char flags,background,aspect; 
} GIFHEADER; 


typedef struct { 

unsigned short int left,top,width,depth; 
unsigned char flags; 

} GIFIMAGEBLOCK; 


typedef struct { 

char blocksize; 
char flags; 

unsigned short int delay; 
char transparent_colour; 
char terminator; 

} GIFCONTROLBLOCK; 


The GIFLIB.CPP source code. 







CompuServe GIF files 


gpfgui *P Tl 

•C m j|..,|tji 

1 $ 




Continued. 

typedef struct { 

char blocksize; 

unsigned short int left,top; 

unsigned short int gridwidth,gridheight; 

char cellwidth,cellheight; 

char forecolour,backcolour; 

} GIFPLAINTEXT; 

typedef struct { 

char blocksize; 
char applstring[8]; 
char authentication[3]; 

} GIFAPPLICATION; 

void GIFDoSkipExtension(int fh) ; 
int GIFDoUnpacklmage(int fh,int bits, 

LPBITMAPINFOHEADER lpbi,int flags); 
int GIFWriteScreenDesc(int fh,LPBITMAPINFOHEADER lpbi,LPSTR sig); 
int GIFWritelmageDesc(int fh,LPBITMAPINFOHEADER lpbi); 
void GIFInitTable(int min_code_size); 
int GIFFlush(int fh,int n); 
void GIFWriteCode(int fh,int code); 

int GIFCompressImage(int fh,LPBITMAPINFOHEADER lpbi); 
int GIFWriteComment(int fh,LPSTR comment); 

LPINT oldcode; 

LPINT currentcode; 

LPSTR newcode; 

char code_buffer[259]; /* where the codes go */ 

int code_size; 
int clear_code; 
int eof_code; 
int bit_offset; 
int byte_offset; 
int bits_left; 
int max_code; 
int free_code; 

WORD error=NO_ERROR; 

#ifdef WIN32 

#pragma argsused 

DLL_EXPORT (BOOL) DllEntryPoint(HINSTANCE hlnstance, 

DWORD wDataSeg,LPVOID lpCmdLine) 

{ 

hlnst=hlnstance; 
return(TRUE); 

} 

#else 
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#pragma argsused 

DLL_EXPORT (int) LibMain(HANDLE hlnstance, 

WORD wDataSeg,WORD wHeapSize, LPSTR lpCmdLine) 

{ 

hlnst=hlnstance; 

if (wHeapSize > 0) UnlockData(0); 
return(TRUE); 

} 

#pragma argsused 

DLL_EXPORT (int) WEP(int nParameter) 

{ 

return (TRUE); 

} 

#endif 

DLL_EXPORT (LPSTR) GetFileExtension() 

{ 

return("GIF"); 

} 

DLL_EXPORT (WORD) GetLibraryVersion() 

{ 

return((VERSION « 8) ! SUBVERSION); 

} 

ttdefine DestroyAllObjects(err,success) {\ 

if(fh != -1) _lclose(fh);\ 

if(!success && handle != NULL) GlobalFree(handle);\ 
error=err;\ 

} 

DLL_EXPORT (HANDLE) GetFilelnformation(LPSTR path) 

{ 

HANDLE handle=NULL; 

GIFHEADER gh; 

GIFIMAGEBLOCK iblk; 
char palette[768]; 
unsigned int width,depth,bits; 
int b,c,fh; 

Initialize() ; 

if((fh=_lopen(path,OF_READ))==-l) { 

DestroyAllObj ects(BAD_OPEN,FALSE) ; 
return(NULL); 

} 

if(_lread(fh,(LPSTR)&gh,sizeof(GIFHEADER)) != 

sizeof(GIFHEADER) !! mememp(gh.sig, "GIF", 3)) { 

_llseek(fh,128L,0); 

if(_lread(fh,(LPSTR)&gh,sizeof(GIFHEADER)) != 







Continued. Figu 

sizeof(GIFHEADER) !! memcmp(gh.sig, "GIF", 3)) { 

DestroyAllObj ects(BAD_FILE,FALSE) ; 
return(NULL); 

} 

} 

bits=(gh.flags & 0x0007) + 1; 
if (gh.flags & 0x80) { 

c=3*(1 << bits); 
if(_lread(fh,palette,c) != c) { 

DestroyAllObjects(BAD_READ,FALSE); 
return(NULL); 

} 

} 

c = 0 ; 

while((c=getbyte(fh)) != EOF && 

(c ==' , 1 ! ! c ==' ! ' !! c & OxOOff)) { 
if (c == ' , 1 ) { 

if(_lread(fh,(LPSTR)fciblk,sizeof(GIFIMAGEBLOCK)) != 

sizeof(GIFIMAGEBLOCK)) { 

DestroyAllObjects(BAD_READ,FALSE); 
return(NULL); 

} 

width=iblk.width; 
depth=iblk.depth; 

if(iblk.flags & 0x80) { 

bits=(iblk.flags & 0x0007) + 1; 
b=3* (l«bits) ; 

if(_lread(fh,palette,b) != b) { 

DestroyAllObjects(BAD_READ,FALSE); 
return(NULL); 

} 

} 

if((handle=CreateDibHeader(width,depth, 
palette,bits))==NULL) { 

DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

} 

DestroyAllObjects(NO_ERROR,TRUE); 
return(handle); 

} 

else if(c == '!' ) GIFDoSkipExtension(fh); 

} 

DestroyAllObjects(BAD_READ,FALSE); 
return (NULL) ; 
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#undef DestroyAllObjects() 

#define DestroyAllObjects(err,success) {\ 

if(fh != -1) _lclose(fh);\ 
if(lpbi != NULL) GlobalUnlock(handle);\ 
if(!success && handle != NULL) GlobalFree(handle);\ 
error=err;\ 

} 

DLL_EXPORT (HANDLE) ReadGraphicFile(LPSTR path) 

{ 

LPBITMAPINFOHEADER lpbi=NULL; 

HANDLE handle=NULL; 

GIFHEADER gh; 

GIFIMAGEBLOCK iblk; 
char palette[768]; 
unsigned int width,depth,bits; 
int b,c,fh; 

Initialize(); 

if((fh=_lopen(path,OF_READ))==-l) { 

DestroyAllObjects(BAD_OPEN,FALSE); 
return(NULL); 

} 

if(_lread(fh,(LPSTR)&gh,sizeof(GIFHEADER)) ! = 

sizeof(GIFHEADER) !! memcmp(gh.sig, "GIF", 3)) { 

_llseek(fh,128L,0); 

if(_lread(fh,(LPSTR)&gh,sizeof(GIFHEADER)) != 

sizeof(GIFHEADER) !! memcmp(gh.sig, "GIF", 3)) { 

DestroyAllObjects(BAD_FILE,FALSE); 
return(NULL); 

} 

} 

bits=(gh.flags & 0x0007) + 1; 
if (gh.flags & 0x80) { 

c=3*(1 << bits); 
if(_lread(fh,palette,c) != c) { 

DestroyAllObjects(BAD_READ,FALSE); 
return(NULL); 

} 

} 

c=0 ; 

while((c=getbyte(fh)) != EOF && 

(c ==' , ' !! c == 1 ! 1 !! c & OxOOff)) { 

if (c == ',') { 

if(_lread(fh,(LPSTR)&iblk,sizeof(GIFIMAGEBLOCK)) != 

sizeof(GIFIMAGEBLOCK)) { 
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DestroyAllObj ects(BAD_READ,FALSE) ; 
return(NULL); 

} 

widthsiblk.width; 
depth=iblk.depth; 

if(iblk.flags & 0x80) { 

bits=(iblk.flags & 0x0007) + 1; 
b=3* (l«bits) ; 

if(_lread(fh,palette,b) != b) { 

DestroyAllObjects(BAD_READ,FALSE); 
return(NULL); 

} 

} 

if((handle=CreateDib(width,depth, 
palette,bits))==NULL) { 

DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

} 

if((lpbi=(LPBITMAPINFOHEADER) 

GlobalLock(handle)) == NULL) { 

DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

} 

if((c=getbyte(fh))==EOF) { 

_lclose(fh); 
return(NULL); 

} 

error=GIFDoUnpackImage(fh,c,lpbi,(int)iblk.flags); 
DestroyAllObjects(NO_ERROR,TRUE); 
return(handle); 

} 

else if(c == '!') GIFDoSkipExtension(fh); 


DestroyAllObjects(BAD_FILE,FALSE); 
return(NULL); 

} 

#undef DestroyAllObjects() 

#define DestroyAllObjects(err,success) {\ 

if(fh != -1) _lclose(fh);\ 

if(fh != -1 && !success) DeleteFile(path);\ 
if(lpbi != NULL) GlobalUnlock(handle);\ 
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if(bp != NULL) FixedGlobalFree(bp);\ 
error=err;\ 

} 

DLLJEXPORT (WORD) WriteGraphicFile(LPSTR path, HANDLE handle) 

{ 

LPBITMAPINFOHEADER lpbi=NULL; 

LPSTR bp=NULL; 

unsigned long size; 

int fh; 

if((fh=_lcreat(path,0))==-l) { 

DestroyAllObj ects(BAD_CREATE,FALSE); 
return(FALSE); 

} 

if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(handle))==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(FALSE); 

} 

if(LPBbits(lpbi) >8) { 

DestroyAllObjects(TOO_MANY_BITS,FALSE); 
return(FALSE); 

} 

size=(DWORD)(GIFTABLESIZE*sizeof(int))+ 

(DWORD)(GIFTABLESIZE*sizeof(int))+ 

(DWORD)GIFTABLESIZE; 

if((bp=(LPSTR)FixedGlobalAlloc(size))==NULL) { 
DestroyAllObjects(BAD_CREATE,FALSE); 
return(FALSE); 

} 

oldcode= (int far *)bp; 

currentcode=(int far *)(bp + GIFTABLESIZE*sizeof(int)); 

newcode=(bp + GIFTABLESIZE*sizeof(int) + 

GIFTABLESIZE*sizeof(int)); 

#if WRITE_GIF89 

if(!GIFWriteScreenDesc(fh,lpbi,GIFSIG89)) { 

DestroyAllObjects(BAD_WRITE,FALSE); 
return(FALSE); 

} 

#else 

if(!GIFWriteScreenDesc(fh,lpbi,GIFSIG87)) { 

DestroyAllObjects(BAD_WRITE,FALSE); 
return(FALSE); 

} 

#endif 

if(!GIFWritelmageDesc(fh,lpbi)) { 
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DestroyAllObj ects(BAD_WRITE,FALSE) ; 
return(FALSE); 

} 

if(!GIFCompressImage(fh,lpbi)) { 

DestroyAllObjects(BAD_WRITE,FALSE); 
return(FALSE); 

} 

#if WRITE_GIF89 

if(!GIFWriteComment(fh,GIFCOMMENT)) { 

DestroyAllObjects(BAD_WRITE,FALSE); 
return(FALSE); 

} 

#endif 

if(putbyte(';',fh)==EOF) { 

DestroyAllObjects(BAD_WRITE,FALSE); 
return(FALSE); 

} 

DestroyAllObjects(NO_ERROR,TRUE); 
return(TRUE); 

} 

#undef DestroyAllObjects() 

DLL_EXPORT (WORD) GetError(LPSTR text) 

{ 

if(text != NULL) Istrepy(text,GetErrorText(error)); 
return(error); 

} 

DLL_EXPORT (LPSTR) GetCopyright() 

{ 

return("Copyright \251 1995 Alchemy Mindworks Inc."); 

} 

DLL_EXPORT (LPSTR) GetNotice() 

{ 

return( 

"GIF supports from one to eight bits of colour.\n\n" 

"WARNING!!!\n" 

"The LZW compression used in the GIF format has been\n" 

"the subject of a surprise patent by the Unisys corporation.\n" 

"If you implement GIF in a commercial or shareware\n" 

"application, or in software included with a larger\n" 

"for-profit product, Unisys may demand royalties from you\n" 

"based on the retail price of your product, as well as requiring\n" 
"that you undertake additional accounting on its behalf and\n" 
"possibly adding additional license restrictions to your\n" 

"software.\n\nThis is very nasty.\n\n" 

"Unless you have a compelling reason to do otherwise, it is\n" 


Figure 3-4 









Figure 3=4 



Chapter 3 



Continued. 


"strongly recommended that you do not use GIF in your\n" 
"applications." 

) ; 


#define PutLine(p,n) hmemcpy(LPBimage(lpbi)+\ 

(DWORD)LPBlinewidth(lpbi)*(DWORD)(LPBdepth(lpbi)-(n)-1),\ 
(p),(DWORD)LPBlinewidth(lpbi)) 


#define DestroyAllObjects() { \ 

if(extrabuffer ! = NULL) FixedGlobalFree(extrabuffer);\ 
if(linebuffer !=NULL) FixedGlobalFree(linebuffer);\ 
if(firstcodestack != NULL) FixedGlobalFree(firstcodestack);\ 
} 

int GIFDoUnpacklmage(int fh,int bits, 

LPBITMAPINFOHEADER lpbi,int flags) 

{ 


int 

bits2; 

/* 

Bits plus 1 */ 

int 

codesize; 

/* 

Current code size in bits */ 

int 

codesize2; 

/* 

Next codesize */ 

int 

nextcode ; 

/* 

Next available table entry */ 

int 

thiscode; 

/* 

Code being expanded */ 

int 

oldtoken; 

/* 

Last symbol decoded */ 

int 

currentcode; 

/* 

Code just read */ 

int 

oldcode; 

/* 

Code read before this one */ 

int 

bitsleft; 

/* 

Number of bits left in *p */ 

int 

blocksize; 

/* 

Bytes in next block */ 

int 

line=0; 

/* 

next line to write */ 

int 

byte=0; 

/* 

next byte to write */ 

int 

pass=0; 

/* 

pass number for interlaced pictures 

int 

i; 

/* 

scratch integer */ 


unsigned int linewidth; 


LPSTR p; /* Pointer to current byte in read buffer */ 

LPSTR q; /* Pointer past last byte in read buffer */ 

char b[255]; /* Read buffer */ 

LPSTR u; /* Stack pointer into firstcodestack */ 


LPSTR linebuffer=NULL; 
LPSTR extrabuffer=NULL; 


/* place to store the current line */ 

/* place to convert the current line */ 


LPSTR firstcodestack=NULL; 
LPSTR lastcodestack; 
short int far *codestack; 


static int wordmasktable[] = { 

0x0000,0x0001,0x0003,0x0007, 
OxOOOf,OxOOlf,0x003f,0x007f, 
OxOOff,OxOlff,0x03ff,0x07ff, 
OxOfff,Oxlfff,0x3fff,0x7fff 
}; 


static int inctablef] = { 8,8,4,2,0 }; /* interlace increments */ 
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static int startable[] = { 0,4,2,1,0 }; /* interlace starts */ 

linewidth=LPBwidth(lpbi); 

if((firstcodestack=(LPSTR)FixedGlobalAlloc(16384))==NULL) { 
DestroyAllObjects(); 
return(BAD_ALLOC); 

} 

lastcodestack=firstcodestack+4096; 

codestack=(short int far *)(lastcodestack+4096); 

p=q=b; 

bitsleft = 8; 

if (bits < 2 !! bits > 8) return(BAD_FILE); 
bits2 = 1 << bits; 
nextcode = bits2 + 2; 

codesize2 = 1 « (codesize = bits + 1); 
oldcode=oldtoken=NO_CODE; 

if((linebuffer= 

(LPSTR)FixedGlobalAlloc(linewidth+1024)) == NULL) { 
DestroyAllObjects(); 
return(BAD_ALLOC); 

} 

if((extrabuffer= 

(LPSTR)FixedGlobalAlloc(linewidth+1024)) == NULL) { 
DestroyAllObjects(); 
return(BAD_ALLOC); 

} 

/* loop until something breaks */ 

for(;;) { 

if(bitsleft==8) { 

if (++p >= q 8c8c 

(((blocksize = getbyte(fh)) < 1) !! 

(q=(p=b)+_lread(fh,b,blocksize))< (b+blocksize))) { 

DestroyAllObjects(); 
return(BAD_FILE); 

} 

bitsleft = 0; 

} 

thiscode = *p; 

if ((currentcode=(codesize+bitsleft)) <= 8) { 

*p >>= codesize; 
bitsleft = currentcode; 

} 

else { 

if(++p >= q && 

(((blocksize = getbyte(fh)) < 1) !! 
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(q=(p=b)+_lread(fh / b / blocksize)) < (b+blocksize))) { 
DestroyAllObjects(); 
r e turn(BAD_FILE); 

} 

thiscode != *p « (8 - bitsleft); 

if(currentcode <= 16) *p >>= (bitsleft=currentcode-8); 
else { 

if(++p >= q && 

(((blocksize = getbyte(fh)) < 1) !! 

(q=(p=b) + _lread(fh,b,blocksize)) < 
(b+blocksize))) { 

DestroyAllObjects(); 
return(BAD_FILE); 

} 

thiscode != *p « (16 - bitsleft); 

*p »= (bitsleft = currentcode - 16) ; 

} 

} 

thiscode &= wordmasktable[codesize]; 
currentcode = thiscode; 

if(thiscode == (bits2+l)) break; /* found EOI */ 

if(thiscode > nextcode) { 

DestroyAllObjects() ; 
return(BAD_FILE); 


if(thiscode == bits2) { 

nextcode = bits2 + 2; 

codesize2 = 1 << (codesize = (bits + 1)); 

oldtoken = oldcode = NO_CODE; 

continue; 


u = firstcodestack; 

if(thiscode==nextcode) { 

if(oldcode==NO_CODE) { 

DestroyAllObjects(); 
return(BAD_FILE); 

} 

*u++ = (char )oldtoken; 
thiscode = oldcode; 


while (thiscode >= bits2) { 

*u++ = lastcodestack[thiscode]; 
thiscode = codestack[thiscode]; 


oldtoken = thiscode; 
do { 
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linebuffer[byte++]=(char)thiscode; 
if(byte >= LPBwidth(lpbi)) { 

if(LPBbits(lpbi)==1) { 

for(i=0;i<LPBwidth(lpbi);++i) { 

if(linebuffer[i]) 

extrabuffer [i»3 ] ! = 

(char)masktable[i & 0x0007]; 

else 

extrabuffer[i>>3] &= 

(char)-masktable[i & 0x0007]; 

} 

PutLine(extrabuffer,line) ; 

} 

else if(LPBbits(lpbi) > 1 && LPBbits(lpbi) <=4) 

for(i=0;i<LPBwidth(lpbi);++i) { 

PutChunkyPixel(extrabuffer,i, 
linebuffer[i] & OxOf); 

} 

PutLine(extrabuffer,line); 

} 

else { 

PutLine(linebuffer,line); 

} 

byte=0; 

/* check for interlaced image */ 
if(flags & 0x40) { 

line+=inctable[pass]; 
if(1ine > = LPBdepth(lpbi)) 
line=startable[++pass]; 

} else ++line; 

} 

if (u <= firstcodestack) break; 
thiscode = *--u; 

} whiled) ; 

if(nextcode < 4096 && oldcode != NO_CODE) { 
codestack[nexteode] = oldcode; 
lastcodestack[nexteode] = (char)oldtoken; 
if (++nextcode >= codesize2 && codesize < 12) 
codesize2 = 1 << ++codesize; 

} 

oldcode = currentcode; 


DestroyAllObjects(); 
return(NO_ERROR); 


Figure 3-4 
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} 

#undef DestroyAllObjects() 

#undef PutLine() 

static void GIFDoSkipExtension(int fh) 

{ 

GIFPLAINTEXT pt; 

GIFCONTROLBLOCK cb; 

GIFAPPLICATION ap; 
int c,n; 

c = 0; 

_lread(fh,(LPSTR)&c, 1); 
switch(c) { 

case 0x0001: /* plain text descriptor */ 

if(_lread(fh,(LPSTR)&pt,sizeof(GIFPLAINTEXT)) 

== sizeof(GIFPLAINTEXT)) { 
do { 

n=0; 

if(_lread(fh,(LPSTR)&n,1)==1) 
_llseek(fh / (long)n,l); 

} while(n > 0); 

> 

break; 

case 0x00f9: /* graphic control block */ 

_lread(fh,(LPSTR)&cb,sizeof(GIFCONTROLBLOCK)); 
break; 

case OxOOfe: /* comment extension */ 

n=0; 
do { 

n=0; 

if(_lread(fh,(LPSTR)&n,1)==1) 

_llseek(fh,(longjn,!); 

} while(n > 0) ; 
break; 

case OxOOff: /* GIFAPPLICATION extension */ 

if(_lread(fh,(LPSTR)&ap,sizeof(GIFAPPLICATION)) 
== sizeof(GIFAPPLICATION)) { 
do { 

n=0; 

if(_lread(fh,(LPSTR)&n,1)==1) 
_llseek(fh,(long)n,l); 

} while(n > 0); 

} 

break; 

default: /* something else */ 

do { 

n=0; 

if(_lread(fh,(LPSTR)&n,1)==1) 

_llseek(fh,(long)n,l); 

} while(n > 0); 
break; 










Continued. 

} 

} 

int GIFWriteScreenDesc (int fh, LPBITMAPINFOHEADER lpbi,LPSTR sig) 

{ 

GIFHEADER gh; 
char palette[768]; 
int n; 

memset((LPSTR)&gh,0,sizeof(GIFHEADER)); 
memcpy(gh.sig,sig,6); 

gh.screenwidth=(short int)LPBwidth(lpbi); 
gh.screendepth=(short int)LPBdepth(lpbi); 
gh. backgrounds ; 
gh. aspects ; 

gh.flags = (char)(0x80 ! 

( (LPBbits (lpbi) -1) «4) ! 

((LPBbits(lpbi)-1) & 0x07)); 

if(_lwrite(fh,(LPSTR)&gh,sizeof(GIFHEADER)) 

!= sizeof(GIFHEADER)) 
return(FALSE); 

GetDibPalette((LPBITMAPINFO)lpbi,palette); 
n=3* (l«LPBbits (lpbi) ) ; 

if(_lwrite(fh,palette,n) != n) return(FALSE); 
return(TRUE); 

} 

int GIFWritelmageDesc(int fh,LPBITMAPINFOHEADER lpbi) 

{ 

GIFIMAGEBLOCK ib; 

memset((LPSTR)&ib,0,sizeof(GIFIMAGEBLOCK)); 
putbyte(', 1 ,fh); 

ib. lefts ; 
ib.top=0; 

ib.widths(short int)LPBwidth(lpbi); 
ib.depth=(short int)LPBdepth(lpbi); 

ib.flags=(char)(LPBbits(lpbi)-1); 

if(_lwrite(fh,(LPSTR)&ib,sizeof(GIFIMAGEBLOCK)) != 

sizeof(GIFIMAGEBLOCK)) 
return(FALSE); 

return(TRUE); 


Figure 3-4 
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} 

void GIFInitTable(int min_code_size) 

{ 

int i; 

code_size=min_code_size+l; 
clear_code=(l<<min_code_size); 
eof_code=clear_code+l; 
free_code=clear_code+2; 
max_code= (l«code_size) ; 

for(i=0;i<GIFTABLESIZE;i++) currentcode[i]=0; 

} 

int GIFFlush(int fh,int n) 

{ 

putbyte(n, fh); 

if(_lwrite(fh,code_buffer,n) != n) return(FALSE); 
else return(TRUE); 

} 

void GIFWriteCode(int fh,int code) 

{ 

long temp; 

byte_offset = bit_offset » 3; 
bits_left = bit_offset & 7; 

if(byte_offset >= 251) { 

GIFFlush(fh,byte_offset); 

code_buffer[0] = code_buffer[byte_offset]; 
bit_offset = bits_left; 
byte_offset = 0; 

} 

if(bits_left > 0) { 

temp = ((long)code « bits_left) ! 

code_buffer[byte_offset]; 
code_buffer[byte_offset]=(char)temp; 
code_buffer[byte_offset+1]=(char)(temp » 8); 
code_buffer[byte_offset+2]=(char)(temp » 16); 

} 

else { 

code_buffer[byte_offset] = (char)code; 
code_buffer[byte_offset+1 ]= (char)(code » 8); 

} 

bit_offset += code_size; 

} 

#define GetLine(p,n) hmemcpy((p),LPBimage(lpbi)+\ 

(DWORD)LPBlinewidth(lpbi)*(DWORD)(LPBdepth(lpbi)-(n)-1),\ 
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Continued. 

(DWORD)LPBlinewidth(lpbi)) 

int GIFCompressImage(int fh,LPBITMAPINFOHEADER lpbi) 

{ 

LPSTR linebuffer,extrabuffer; 
int prefix_code; 
int suffix_char; 
int hx,d,min_code_size; 

int bytes_left=0,next_byte=0,this_line=0; 
int i ; 

unsigned int linewidth; 

1inewidth=LPBwidth(lpbi); 

if((linebuffer=(LPSTR)FixedGlobalAlloc(linewidth+1024))==NULL) 
return(BAD_ALLOC); 

if((extrabuffer=(LPSTR)FixedGlobalAlloc(linewidth+1024))==NULL) 
FixedGlobalFree(linebuffer); 
return(BAD_ALLOC); 

} 

min_code_size=LPBbits(lpbi); 
if (min_code_size < 2 I! min_code_size > 9) { 

if(min_code_size == 1) min_code_size = 2; 
else { 

FixedGlobalFree(extrabuffer); 

FixedGlobalFree(linebuffer); 
return(BAD_WRITE); 

} 

} 


putbyte(min_code_size,fh); 
bit_offset=0; 

GIFInitTable(min_code_size); 
GIFWriteCode(fh,clear_code); 


GetLine(linebuffer,this_line++); 


if(LPBbits(lpbi)==1) { 

lmemcpy(extrabuffer,linebuffer,LPBlinewidth(lpbi)); 
for(i=0;i<LPBwidth(lpbi);++i) { 

if (extrabuffer [i»3] & masktable[i & 0x0007]) 
linebuffer[i]=1; 

else 


} 


linebuffer[i]=0; 


else if(LPBbits(lpbi) > 1 && LPBbits(lpbi) <= 4) { 

lmemcpy(extrabuffer,linebuffer,LPBlinewidth(lpbi)); 
for(i=0;i<LPBwidth(lpbi);++i) { 

linebuffer[i]=GetChunkyPixel(extrabuffer,i); 


Figure 3-4 
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bytes_left=LPBwidth(lpbi)-l; 

next_byte=0; 

suffix_char=linebuffer[next_byte++]; 

prefix_code = suffix_char; 

for(;;) { 

if(bytes_left) { 

suffix_char=linebuffer[next_byte++]; 

-~bytes_left; 

} 

else { 

if(this_line >= LPBdepth(lpbi)) break; 

GetLine(linebuffer,this_line++); 

if(LPBbits(lpbi)==1) { 

lmemcpy(extrabuffer,linebuffer, 

LPBlinewidth(lpbi)); 
for(i=0;i<LPBwidth(lpbi);++i) { 

if(extrabuffer[i>>3] & masktable[i & 0x0007]) 
linebuffer[i]=1; 

else 

linebuffer[i]=0; 

} 

; > 

else if(LPBbits(lpbi) > 1 && LPBbits(lpbi) <= 4) { 

lmemcpy(extrabuffer,linebuffer, 
LPBlinewidth(lpbi)); 
for(i=0;i<LPBwidth(lpbi);++i) { 

linebuffer[i]=GetChunkyPixel(extrabuffer,i); 

} 

} 

bytes_left=LPBwidth(lpbi)-l; 

next_byte=0; 

suffix_char=linebuffer[next_byte++]; 

} 

hx=(prefix_code ^ (suffix_char << 5)) % GIFTABLESIZE; 
d=l; 

for(;;) { 

if(currentcode[hx] == 0) { 

GIFWriteCode(fh,prefix_code); 
d = free_code; 



if(free_code <= GIFLARGESTCODE) { 
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oldcode[hx] = prefix_code; 
newcode[hx] = (char)suffix_char; 
currentcode[hx] = free_code; 
free_code++; 

} 

if(d == max_code) { 

if(code_size < 12) { 

code_size++; 
max_code < < = 1; 

> 

else { 

GIFWriteCode(fh,clear_code); 
GIFInitTable(min_code_size); 

} 

} 

prefix_code = suffix_char; 
break; 

} 

if(oldcode[hx] == prefix_code && 
newcodefhx] == suffix_char) { 
prefix_code = currentcode[hx]; 
break; 

} 

hx += d; 
d += 2; 

if(hx >= GIFTABLESIZE) hx -= GIFTABLESIZE; 

} 

} 

GIFWriteCode(fh,prefix_code); 

GIFWriteCode(fh,eof_code); 

if(bit_offset > 0) GIFFlush(fh,(bit_offset+7)/8); 

if(!GIFFlush(fh,0)) { 

FixedGlobalFree(extrabuffer); 

FixedGlobalFree(linebuffer); 

return(FALSE); 

} 

FixedGlobalFree(extrabuffer); 

FixedGlobalFree(linebuffer); 

return(TRUE); 

} 

#undef GetLine() 

int GIFWriteComment(int fh,LPSTR comment) 

{ 


Figure 3“4 
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int n; 

n=lstrlen(comment); 

putbyte( ' ! ' ,fh); 
putbyte(Oxfe,fh); 

do { 

if(n > 255) { 

putbyte(255,fh); 

if(_lwrite(fh,comment,255) ! = 255) return(FALSE); 

comment +=255; 
n-=255; 

} 

else { 

putbyte (n, fh) ; 

if(_lwrite(fh,comment,n) != n) return(FALSE); 
putbyte(0,fh); 
n=0 ; 

} 

} while(n); 
return(TRUE); 

} 


It then works out the bit depth of the global color map and loads the 
global color map if one exists. 

The while loop in ReadGraphicFile steps through the blocks in the 
GIF file being read. If it encounters an image block—as indicated by a 
comma—it reads the first portion of the block in a GIFIMAGEBLOCK 
object. It can then determine the image dimensions, color depth and 
the local color map if it exists, and call CreateDIB to return a handle 
to a suitable device-independent bitmap. The next byte after the 
GIFIMAGEBLOCK object is the initial code size. 

In this version of the GIF reader, the GlFDoUnpacklmage function is 
called to unpack the image, then the function returns with a handle to 
the bitmap created by CreateDIB. We’ll discuss GlFDoUnpacklmage 
in a moment. A more complete GIF reader would loop through all the 
blocks in a GIF file, doing something with each image it encountered. 
Having ReadGraphicFile return after the first image makes GIFLIB 
compatible with the general structure of the VIEWER application— 
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you’d want to modify this if you were creating a more fully compliant 
GIF reader. 

If the block being read begins with an exclamation point, the 
GlFDoSkipExtension function is used to skip over the following 
extension block. Extension blocks are ignored by GIFLIB.CPP as it 
stands, as VIEWER doesn’t really have a place for GIF extension 
blocks in its simplified view of the universe. This function reads the 
contents of extension blocks but does nothing with them. 

The real work of ReadGraphicFile is handled by 
GlFDoUnpacklmage —an ancient and hoary bit of code that leans 
more toward being efficient than lucid. It has evolved through years of 
tinkering. 

The three objects that were discussed at the beginning of this 
chapter—the code and character streams and the code stack—are 
allocated before GlFDoUnpacklmage does anything else. It’s 
important to note that the code stack is an array of 4096 short 
integers, rather than merely being ints. Both are 16-bit objects for 
Windows 3.1 application, but an int in 32-bit environment is a 4-byte 
object and will not fit in the allocated memory. The 
GlFDoUnpacklmage function allocates two line buffers—one to store 
the 1-byte pixels as they emerge from the decoder and a second one 
to swab said pixels into for bitmaps have 16 or fewer colors. 

The bits I eft value is the number of bits of source information that 
have been read but not decoded. Keep in mind that LZW compression 
wants to work with strings of bits. In this case, there can be no more 
than 12 bits in a string, so a short integer is suitable to store the 
strings in. 

The compressed data in a GIF image is stored in fields, with each field 
consisting of a length byte followed by the appropriate number of data 
bytes. The last byte in an image block’s data will be a zero-length byte. 

You can see how these fields are parsed and read at the top of the for 
loop. The GlFDoUnpacklmage function would like to read LZW 
compressed data one byte at a time, but as this is impractically slow, it 
implements a very simple buffering procedure based on the length of a 
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compressed data field. It winds up with the current code to be 
decompressed in thiscode. 

Not all the bits in thiscode are necessarily significant—this value is 
masked using the wordmasktable array based on the current code 
size. 

The rest of the loop in GlFDoUnpacklmage deals with searching the 
code stack for thiscode and adding it to the stack if it turns out not to 
be there. Most of the work being done in the lower half of the loop 
deals with swabbing the one byte per pixel lines of GIF data into 
suitable lines for a device-independent bitmap. 

The WriteGraphicFile function in GIFLIB deals with compressing the 
image in a device-independent bitmap into a GIF file. Depending upon 
the state of WRITE_GIF89 at the top of GIFLIB. CPP, it can create 
either GIF 87a or GIF 89a files. The latter will include a comment 
block with the text defined by GIFCOMMENT. 

Writing a GIF file is inherently simpler than reading one, although the 
code to do so sprawls out a bit in GIFLIB.CPP. The WriteGraphicFile 
function begins by creating the destination file and locking the source 
bitmap. Because the GIF format can only support a maximum of 256 
colors, or 8 bits of color depth, it will return an error if it finds it’s 
being asked to compress a true color image. It then allocates its three 
stack objects and gets to work. 

The GIF writer in WriteGraphicFile is hardwired to produce single¬ 
image GIF files to some extent—you’d want to change it if you need 
more complex GIF files, having multiple images or extension blocks. 
The GIF writer in GIF Construction Set, for example, writes a variety 
of GIF blocks in any order they’re called for. 

The WriteGraphicFile function calls GlFWriteScreenDesc to write a 
GIF header and screen descriptor. As was touched on earlier, it 
assumes that the screen dimensions of the GIF file to be written will be 
the same as those of the image it will contain. This need not be so, 
and more elaborate GIF applications might require that this be 
changed. 
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The GlFCompressImage function is what does most of the work. It 
does what GlFDoUnpacklmage does, but in reverse. The structure of 
LZW compression makes it fairly easy to see this. The only thing that 
makes this function even moderately complicated is the requirement 
that it break up the data it writes to the destination GIF file into blocks 
of no more than 255 bytes. It must also swab the lines from a device¬ 
independent bitmap into one byte per pixel lines for images having 
four or fewer bits of color. 

The GlFWriteComment function is only called if GIFLIB is set up to 
write GIF 89a files. It packs its comment argument into a number of 
255-byte fields—essentially, into Pascal-style strings. 

Gift wrapped 

If not for the legal issues surrounding it, GIF would be a moderately 
useful format. It’s by now somewhat outdated compression method 
means that it does not compress images as effectively as PNG. It also 
includes no true color image support, a decided drawback. However, 
GIF was well on its way to becoming the single most popular graphic 
standard on earth before Unisys appeared. As I write this, GIF is a 
fixture on the World Wide Web, but rumor has it that it will be 
supplanted by PNG there as well. The PNG format is somewhat more 
complex to implement, but it solves a multitude of problems. 

Unless you’re writing software that has a pressing need to support 
GIF, it’s a really good idea to leave it alone. 























HE PCX standard is one of the oldest image file formats still in 
use on PC systems, and it’s probably the most widely 
supported for things like graphics imported into word processors and 
desktop publishing packages, screen captures, and so on. Originally 
the native format for ZSoft’s ubiquitous PC Paintbrush application, it 
has evolved with the increasing capabilities of PC display hardware 
and has found wide acceptance among third-party software 
developers. 

The creators of PC Paintbrush are only a memory now, as is PC 
Paintbrush for the most part. The format itself lives on. The PCX 
format is also supported under Windows by the Windows Paintbrush 
application as an alternate to its default BMP files. 

If you’ll be creating software that will be exchanging files with a 
variety of other applications—especially if some of them can be 
expected to run under DOS, rather than under Windows—you should 
probably include facilities to handle PCX files. The PCX format is as 
close to a universal graphic standard as PC systems are likely to see. 

Figure 4-1 illustrates a Windows paint application that supports PCX 
files: Corel PhotoPaint. Corel PhotoPaint actually began life with an 
application written by ZSoft, the creators of PCX. It’s part of the 
Corel Draw bundle. 

It’s worth noting that Corel PhotoPaint deals with the problem of 
Windows’ oftentimes limited selection of colors differently than 
Windows Paintbrush. Windows Paintbrush works like a classic painting 
package, such that what gets drawn on the screen is what’s used to 
update the image the software keeps in memory while you’re working. 
As such, if you attempt to edit an image with more colors than 
Windows Paintbrush can support, it will remap the image to the colors 
it does have on hand. When you save your file, it will be saved with 
these fairly crude remapped colors. 

An application like PhotoPaint does everything twice. When you draw 
something under PhotoPaint, it places it in the screen window and 
then in the image stored in memory. This means that it can use a 
fairly crude dithered image on your screen if need be, should it find 
itself confronted with a paucity of colors, but it can still work with your 
source image at its true color depth and with no remapping. 










Corel PhotoPaint. 


This distinction is particularly important if you plan to use Windows 
Paintbrush to create or manipulate test images for the code in this 
book. Also keep in mind that even 16-color PCX files loaded into 
Windows Paintbrush will be remapped to the default Windows palette. 
This can cause pronounced color shifts in some files. 



PCX file structure 


There are several aspects of their history that color the nature of PCX 
files. The first are their antecedents. The original use of PCX files was 
to store drawn, rather than scanned, images. This is perhaps not 
surprising, as the PCX format largely predates the availability of 
affordable image scanners for PC hardware. At the time of its 
introduction, PC Paintbrush was designed to run on very slow 8088- 
based systems. 


Figure 4-1 

























The PCX format uses a particularly simple form of run-length 
encoding. Its encoding method has clearly been designed to be as fast 
to unpack as possible—to compensate for the initial lack of speed of 
the hardware that did the unpacking, perhaps—and to favor drawn 
images; that is, ones with a lot of unbroken areas of solid color. While 
it can be said to have been well optimized for these conditions, the 
run-length encoding procedure used by PCX files falls apart pretty 
quickly when it’s confronted with complex scanned images. It’s not at 
all uncommon to find that scanned images stored in the PCX format 
exhibit substantial negative compression—they get a lot bigger 
compressed than they would be stored as raw image data, as in the 
BMP format, for example. 

The second consideration inherent in PCX files is that they were 
initially designed back before the current generation of PC display 
technology was even a pipe dream in the back rooms of IBM. The 
original design of the PCX format allowed for a maximum of 16 
colors. While PCX files were subsequently bent and twisted to support 
256 colors and more recently 24-bit images, they don’t seem to have 
enjoyed the experience. The 256-color modification is decidedly 
awkward, as will be discussed in a moment. 

The final potential problem with the PCX format is its huge number of 
users. The PCX format was initially defined in a leaflet freely available 
from ZSoft, and this has no doubt helped to make it so widely 
accepted among third-party software developers. However, there are 
several areas in which the wording of the ZSoft specification was 
initially a bit vague and could be interpreted in several different— 
largely incompatible—ways. This has led to the appearance of a 
number of applications that create “illegal” PCX files; that is, files that 
cannot be read correctly by a PCX reader that strictly adheres to the 
PCX standard. 

We’ll be looking at ways to deal with such files—they are all workable, 
but they require a level of stealth and cunning hitherto reserved for 
spies, liberal politicians, and Labrador retrievers trolling for cats. 

A PCX file is a fairly simple entity. It consists of a 128-byte header 
followed by a lot of run-length compressed image data. The 256-color 
PCX standard has a secondary palette tacked onto the end of the 






image data. However, working with the PCX format does not entail 
making sense of blocks, tags, chunks, directories, or extensions. 

The PCX format defines images with between 1 and 4 bits of color as 
interleaved planes—at least, it’s supposed to. Images with 8 bits of 
color are stored with 1 byte per pixel. There are no PCX images with 
5, 6, or 7 bits of color—an image with an intermediate number of 
colors would be promoted to 256 colors if it were to be written to the 
PCX format. Images with 24 bits of color are stored with 3 bytes per 
pixel, although in a rather unusual way. 

The header of a PCX file looks like this: 

typedef struct { 

char manufacturer; 
char version; 
char encoding; 
char bits; 

short int xmin,ymin; 
short int xmax,ymax; 
short int hres; 
short int vres; 
char palette[48]; 
char reserved; 
char color ^planes; 
short int bytes_per_line; 
short int palette_type; 
char filler[58]; 

} PCXHEAD; 

When you open a PCX file, you should begin unpacking it by reading 
the first 128 bytes into a PCXHEAD object. You can subsequently 
figure out how to decode the file’s contents by reading the fields in 
this structure. 

The manufacturer field will always contain the value 10. This is how a 
PCX reader can know that what it has been given to unpack really is a 
PCX file. The version number will tell it what version of PC 
Paintbrush ostensibly created the file. This is actually useful, as it 
defines something about how the palette information in the file should 
be interpreted. 

Specifically, if the version number is 0, the file has come from PC 
Paintbrush version 2.5 and is pretty ancient. If it’s 2, the file was 








written by version 2.8 of PC Paintbrush and contains valid palette 
information. If it’s 3, the file has come from PC Paintbrush 2.8, but it 
does not contain valid palette information. In this case, the file is 
assumed to use a default palette provided by PC Paintbrush. If the 
version is 5, the file was created by version 3.0 of PC Paintbrush or 
better. This is the correct version number for a PCX file having 256 or 
more colors. 

The encoding field specifies the type of image encoding being used in 
the file. At the moment, there is only one type. This field should 
always contain the value 1. 

The bits and planes fields define the number of colors in a file. 
Specifically, the planes value is the number of image planes per line, 
and the bits value is the number of bits per plane. In planar files—for 
example, a 16-color PCX file with four planes per line—these would 
be four and one, respectively. You might think that it’s impossible to 
have more than one bit per plane, a plane being, by definition, a 
single-bit-per-pixel entity. In fact, this is not the case. There are two 
types of PCX files that have multiple-bit planes of a sort. We’ll 
encounter them presently. 

The xmin and ymin values define the upper-left corner of the image 
stored in a PCX file. The xmax and ymax define the lower-right 
corner. The width of a PCX image in pixels can be defined as xmax- 
xmin + 1, and the depth can be defined as ymax-ymin + 1. The xmin 
and ymin values are usually 0, but you shouldn’t count on this always 
being the case. 

The palette_type field will contain 1 for a color palette or 0 for a gray 
scale palette. In fact, both types of palettes are structured identically, 
except that, in the latter, all the colors will be levels of gray. As such, a 
type one palette will always be applicable, even if the colors in it are 
gray. Most PCX readers ignore this field. 

The bytes_per_line value tells a PCX reader how long an unpacked 
image line should be. Note that this will often differ from the value 
calculated by pixels2bytes(xmax-xmin + 1), as some PCX files have 
their lines padded out with extra bytes. 








The palette field contains up to 16 RGB definitions for colors used in 
the file being read. Unfortunately, this is of little use to a 256-color 
image. An 8-bit PCX file will usually have nothing meaningful stored 
in the palette field of its header. 

As was noted previously, a 256-color PCX file actually stores its 
palette information after its compressed image data. As each color in 
a palette requires 3 bytes, this palette will be 768 bytes long. It will 
always be preceded by a byte containing the value 12. As such, you 
can locate the palette in 256-color PCX file by seeking to the end of 
the file and then seeking back 769 bytes. Read the byte at this 
position—if it’s 12, read the next 768 bytes as the palette. If it’s not, 
your PCX file has been infested by mice. 

The PCX file run-length compression strategy is particularly easy to 
understand. Having read the header of a PCX file, the next byte will 
be the first byte of the first compressed image line. To decompress an 
image line, you would read the first byte and check to see if the upper 
2 bits are set. If they are, read the next n bytes from the file, where n 
is the value stored in the lower 6 bits of the first byte you read. 

If the upper 2 bits of the initial byte are not set, the byte is written as 
is to the buffer that you’ll be storing the line information in. 

Having read one field, you would check to see if enough bytes have 
been written to the line buffer to constitute the entire line, as defined 
by the bytes_per_line value of the header. If this is not the case, 
repeat the foregoing procedure and check the total again. 

The compressed lines in a PCX file are constrained to break on even 
line boundaries. In uncompressing a line, you should always reach 
exactly the number of bytes indicated in the bytes_per_line value of 
the header. 

This is a function to read one line of a PCX file. It assumes that 
there’s a buffer at p large enough to contain the uncompressed line 
and that the file indicated by fp is a PCX file with its header having 
been read previously. The value in bytes should be the one in the 
bytes_per_line field of the header. 






PCXReadLine(char *p / FILE *fp,int bytes) 

{ 

int n=0,c,i; 
do { 

c=fgetc(fp); 

if(c==EOF) return(BAD_READ); 
if((c & OxcO) == OxcO) { 
i=c & 0x3f; 
c=fgetc(fp); 

if(c==EOF) return(BAD_READ); 
while(i--) p[n++]=c; 

} 

else p[n++]=c; 

} while(n < bytes); 
if(n==bytes) return(SUCCESS); 
else return(BAD_READ); 

} 

There are several things to note about the run-length compression 
used by PCX files. To begin with, no single field can be longer than 63 
bytes—longer lines require multiple fields even if the lines themselves 
are unbroken runs. Secondly, there is no string field per se in PCX 
encoding. A string of bytes in which all the bytes had their upper 2 
bits set—a pathological case for PCX encoding—would require each 
byte to be stored as a 1-byte run; that is, as 2 bytes. Such a string 
would be twice as long compressed as it would be uncompressed. 

Note that all byte values above 192 would have their upper 2 bits 
set—this means that a quarter of the possible values for pixels in an 
8-bit PCX file having no runs of bytes and an even dispersal of colors 
would have to be stored as 2-byte fields. This should help account for 
the relatively poor compression 256-color PCX files of scanned 
images typically exhibited. 


. PCX Sine formats 



As a rule, PCX image file lines are structured in ways that more or less 
correspond to the PC display hardware that will ultimately handle 
them, assuming they’re to be used by DOS-based software. The 24-bit 
format appears to have been designed to make the best use of the 
PCX format’s run-length compression when it’s applied to the 
formidable task of squeezing true color images. 





Monochrome PCX files are stored with 1 bit plane per line. Images 
having between 2 and 4 bits of color are stored as interleaved 
planes—at least, this is usually the case. The discussion of illegal PCX 
file types to follow will deal with this in greater detail. 

The 24-bit PCX line format consists of 3 planes per line, each plane 
being 8 bits deep. The first plane holds all the red pixels for the line, 
the second all the green pixels, and the third all the blue pixels. This is 
actually a very sensible way to run-length compress 24-bit image 
information, assuming that you want to attempt it at all. Rather than 
being byte oriented, it’s effectively pixel oriented. However, because 
the size of a 24-bit pixel—three—is awkward for a computer to deal 
with, the PCX format manages to compress these pixels as single 
bytes, albeit doing so three times for each line. 

You might want to keep this in mind when the Targa format turns up 
later in this book. It implements run-length compression for 24-bit 
files in a slightly different way. 

In relation to other 24-bit formats, such as BMP and the Targa 
format, it’s interesting to note that PCX is the only one that insists on 
compressing true color images. Targa, for example, gives a file writer 
the option of creating compressed or uncompressed true color files, 
depending on the nature of their contents. 

Sixteen-color PCX files are perhaps the most nettlesome images 
you’re likely to encounter. They represent the most common 
application of the PCX format, being used to store business graphics 
and screen captures among other things. Numerous third-party 
applications create 16-color PCX files. Unfortunately, not all of them 
do so correctly. 

There are three principal variations on the way 16-color lines are 
stored. 

The PCX specification from ZSoft notes that a PCX file writer should 
not compress across line boundaries, as has been discussed. In a 
monochrome PCX file, this would mean that two lines that could be 
compressed as single would always be split into two, such that 





decoding each would leave you with the number of bytes specified in 
the bytes_per_lines field of the header. 

A 16-color PCX file line has four planes. The ZSoft specification 
leaves some doubt as to whether such a line should be stored as four 
distinct planes, each breaking on a plane boundary, or as one plane, 
ending on a line boundary. The latter is easier to do and often results 
in slightly better image compression. The former is actually correct, 
however. 

Here’s how this becomes a bit of a problem. A 16-color PCX file 
having the dimensions 640 by 480 pixels would have a 
bytes_per_line value of 80 and a planes value of 4. There would be 
80 bytes in one plane of a line, and 4 planes per line. If each plane is 
compressed individually, you would be able to uncompress 80 bytes of 
the first plane, followed by 80 bytes of the second, and so on. 

If all 320 bytes of the four planes are compressed together and if one 
of the planes happens to end with the same byte value as the next 
plane begins with, calling the PCXReadLine function discussed 
previously with a bytes argument of 80 will cause it to fail and return 
the BAD_READ constant. The first plane will not end until more than 
80 bytes have been unpacked. Some of them will belong to the second 
plane, of course, but PCXReadLine won’t know this. 

The obvious way around this would be to pass PCXReadLine a value 
that would cause it to read all four planes at once, as this will work 
whether a line has been compressed as one object or as four. In fact, 
while this will keep PCXReadLine from failing, it will present you with 
very peculiar looking PCX images some of the time. Because the 
number of bytes in a plane might be padded out with an extra byte on 
some cases, PCX images with horizontal dimensions that aren’t evenly 
divisible by eight might have each plane offset by one byte, resulting in 
a picture that looks to have several colored shadows behind everything 
in it. This looks interesting on album covers and old posters but is less 
than desirable for most graphic applications. 

There is no obvious way to discern whether a 16-color PCX file has been 
compressed properly or not—except, perhaps, by reading all the lines 
and seeing if any of the compressed plane fields come out too long. This 




would be awkward at best. There is a way to get around the problem, 
however. If you read all 16-color lines as if they were compressed as 
single planes and then copy the individual planes into a second buffer, 
you will wind up with correctly formatted lines in all cases. The source 
planes will be separated by the number of bytes in the bytes_per_line 
field of the header. The destination lines should be separated by the 
number of bytes defined as pixels2bytes(xmax-xmin+1). 

This takes care of pretty well all the illegal planar 16-color PCX files 
you’re likely to encounter. However, there is one more variation, and 
it’s peculiar to Windows. 

While it does not appear to be documented by ZSoft, there’s a second 
common mutation of 16-color PCX files. This one doesn’t store PCX 
images in planes at all. It implements the same chunky pixel format 
that Windows uses to store lines of its 4-bit device-independent 
bitmaps. Each byte in a line stores two pixels—one in its upper 4 bits 
and a second in its lower 4 bits. This sort of PCX file is accepted by 
the Windows Paintbrush application. 

A PCX reader can decide when it has one of these Windows-specific 
PCX files by looking at the PCX file header. If the image has been 
stored as stacked pixels, there will be one plane and four bits per 
plane, a condition that cannot exist under any other circumstances. 

It’s worth noting that few DOS applications that read PCX files will 
deal with the Windows-specific version of them—except for the DOS 
version of Graphic Workshop. If you’ll be writing software that creates 
PCX files, you should only use this format if the files are intended to 
be read by suitable Windows applications. 

There are arguments in favor of handling 16-color PCX files this way 
if they’re to remain exclusively in the province of Windows software. 

A planar PCX file must be converted into a Windows-style bitmap if 
it’s to be displayed or printed by Windows applications. While this 
isn’t particularly difficult to do, it can be pretty time-consuming, 
requiring a lot of bitwise data manipulation. If you want to write a 
device-independent bitmap to a PCX file, the same level of format 
massaging will be required. 











By comparison, reading and writing these albeit suspect Windows-style 
PCX files is almost instantaneous, as the line data will be in the format 
you’ll want to use it in. This is quite the opposite case to what you’ll 
find if you try to use Windows-style PCX files in DOS applications, 
such as Graphic Workshop. Graphic Workshop for DOS will read 
Windows-style PCX bitmaps, but it takes its time doing so, as it must 
convert the Windows lines into the sorts of planar lines that can be 
written to a conventional planar 16-color display. 

The PCX reader code to be discussed in this chapter will perform all 
these manipulations transparently. Specifically, it will sort out 16-color 
lines that have been compressed across plane boundaries, and it will 
convert planar lines to Windows lines, except for those PCX files that 
are already in the Windows bitmap format. 


The PCXLIB library 

If you cut and hacked your way through the underbrush of the GIF 
library in the preceding chapter, you’d find the PCX library almost 
effortless. No trace is to be found of code tables, variable-width bitwise 
objects, or lawyers. The structure of PCX files isn’t at all mysterious, 
and neither are the functions to read and write them. The PCXLIB 
ReadGraphicFile function deals with all the illegal line format 
permutations discussed earlier in this chapter. 

Figure 4-2 illustrates the PCXLIB.CPP source code. 

The ReadGraphicFile function in PCXLIB illustrates how to unpack a 
PCX file into a device-independent bitmap. It begins by opening the 
source file and reading the first 128 bytes into a PCXHEAD object. If 
the manufacturer byte of the resulting PCXHEAD is 10, it assumes it 
has a real PCX file and proceeds to unpack its contents. 

Perhaps the most complex aspect of deciphering a PCX header is 
working out the color depth of the file. This will be 24 bits if the bits 
field holds 8 and the color_planes field holds 3. It will be the number 
of color planes if the bits field holds 1 and the value of the bits field 
otherwise. 
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PCX Library 

Copyright (c) 1995 Alchemy Mindworks Inc. 


*/ 


#include 

#include 

#include 

#include 

#include 


<windows.h> 
<stdio.h> 
<string.h> 
<stdlib.h> 
"winbit.h" 


HANDLE hlnst; 


typedef struct { 

char manufacturer; 
char version; 
char encoding; 
char bits; 

short int xmin,ymin; 
short int xmax,ymax; 
short int hres; 
short int vres; 
char palette[48]; 
char reserved; 
char colour_planes; 
short int bytes_per_line; 
short int palette_type; 
char filler[58]; 

} PCXHEAD; 

char pcxpalette[48] = { 

0x00,0x00,0x00, 0x00,0x00,OxAA,0x00,OxAA, 
0x00,0x00,OxAA,OxAA,OxAA,0x00,0x00,OxAA, 
0x00,OxAA,OxAA,0x55,0x00,OxAA,OxAA,OxAA, 
0x55,0x55,0x55,0x55,0x55,OxFF,0x55,OxFF, 
0x55,0x55,OxFF,OxFF,OxFF,0x55,0x55,OxFF, 
0x55,OxFF,OxFF,OxFF,0x5 5,OxFF,OxFF,OxFF, 


WORD PCXReadLine(LPSTR p,int fh,int bytes); 

WORD PCXWriteLine(LPSTR p,int fh,int n); 

WORD error=NO_ERROR; 

#ifdef _WIN32_ 

#pragma argsused 

DLL_EXPORT (BOOL) DllEntryPoint(HINSTANCE hlnstance, 
DWORD wDataSeg,LPVOID lpCmdLine) 

{ 
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hlnst=hlnstance; 
return(TRUE); 

} 

#else 

#pragma argsused 

DLL_EXPORT (int) LibMain(HANDLE hlnstance, 

WORD wDataSeg,WORD wHeapSize, LPSTR lpCmdLine) 

{ 

hlnst=hlnstance; 

if (wHeapSize > 0) UnlockData( 0 ) ; 
return(TRUE); 

} 

#pragma argsused 

DLL_EXPORT (int) WEP(int nParameter) 

{ 

return (TRUE); 

} 

#endif 

DLL_EXPORT (LPSTR) GetFileExtension() 

{ 

return("PCX”); 

} 

DLL_EXPORT (WORD) GetLibraryVersion() 

{ 

return ( (VERSION « 8) ! SUBVERSION); 

} 

#define DestroyAllObjects(err,success) {\ 

if(fh != -1) _lclose(fh);\ 

if(!success && handle != NULL) GlobalFree(handle);\ 
error=err;\ 

} 

DLL_EXPORT (HANDLE) GetFilelnformation(LPSTR path) 

{ 

HANDLE handle=NULL; 

PCXHEAD pcx; 

WORD bits; 

char palette [768] ; 

int fh=-l; 

Initialize(); 

if((fh=_lopen(path,OF_READ))==-l) { 

DestroyAllObjects(BAD_OPEN,FALSE); 
return(NULL); 


} 
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if(_lread(fh,(LPSTR)&pcx,sizeof(PCXHEAD)) != 

sizeof(PCXHEAD) !! 

pcx.manufacturer != 10) { 

DestroyAllObj ects(BAD_0PEN,FALSE); 
return(NULL); 

} 

if(pcx.bits==l) GetMonoPalette(palette); 
else { 

if(pcx.bits==8 && pcx.version >= 5) { 

_llseek(fh,-769L,SEEK_END); 
if(getbyte(fh)==12) { 

if(_lread(fh,palette,768) != 768) { 

DestroyAllObjects(BAD_FILE,FALSE); 
return(NULL); 

} 

} else memcpy(palette,pcx.palette,48); 

} else if(pcx.version == 3) 

memcpy(palette,pcxpalette,48); 

else 

memcpy(palette,pcx.palette,48); 

} 

if(pcx.bits==8 && pcx.colour_planes==3) bits=24; 
else if(pcx.bits==l) bits=pcx.colour_planes; 
else bits=pcx.bits; 

if((handle=CreateDibHeader(pcx.xmax-pcx.xmin+1, 
pcx.ymax-pcx.ymin+1,palette,bits))==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

} 

DestroyAllObjects(NO_ERROR,TRUE); 
return(handle); 

} 

#undef DestroyAllObj ects() 

#define DestroyAllObjects(err,success) {\ 

if(fh != -1) _lclose(fh);\ 

if(linebuffer != NULL) FixedGlobalFree(linebuffer);\ 
if(lpbi != NULL) GlobalUnlock(handle);\ 
if(!success && handle != NULL) GlobalFree(handle);\ 
error=err;\ 

} 

DLL_EXPORT (HANDLE) ReadGraphicFile(LPSTR path) 

{ 

LPBITMAPINFOHEADER lpbi=NULL; 

LPSTR linebuffer=NULL; 

HANDLE handle=NULL; 

PCXHEAD pcx; 
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Figure 4-2 Continued. 

HPSTR pd; 

LPSTR ps; 

char palette[768]; 

unsigned int i,j,k,bytes; 

int width,depth,bits,lbsize; 

int a,fh=-l; 

Initialize(); 

if((fh=_lopen(path,OF_READ))==-l) { 

DestroyAllObj ects(BAD_OPEN,FALSE); 
return(NULL); 

; } 

if(_lread(fh,(LPSTR)&pcx,sizeof(PCXHEAD)) != sizeof(PCXHEAD) !! 

pcx.manufacturer != 10) { 

DestroyAllObjects(BAD_OPEN,FALSE); 
return(NULL); 

} 

if(pcx.bits==8 && pcx.colour_planes==3) bits=24; 

else if(pcx.bits==l) bits=pcx.colour_planes; 

else bits=pcx.bits; 

width=pcx.xmax-pcx. xmin+1; 

depth=pcx.ymax-pcx.ymin+l; 

if((handle=CreateDib(width,depth,palette,bits))==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

: } 

if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(handle)) == NULL) { 
DestroyAllObj ects(BAD_ALLOC,FALSE); 
return(NULL); 

} 



if (bits > 1 ScSc bits <=4) { 

if (pcx.bits==4 Sc&c pcx.colour_^»lanes==l) 
bytes=pcx.bytes_per_line; 

else 

bytes=pcx.bytes_per_line*bits; 

} 

else if(bits==24) 

bytes=pcx.bytes_per_line*RGB_SIZE; 
else 

bytes=pcx.bytes_per_line; 
lbsize=max(bytes,LPBlinewidth(lpbi)); 

if((linebuffer=FixedGlobalAlloc(lbsize+1024))==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
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return(NULL); 

} 

resetbuffer(); 

pd=LPBimage(lpbi)+(DWORD)LPBlinewidth(lpbi)*(DWORD)depth; 

for(i=0;i<depth;++i) { 

pd-=(DWORD)LPBlinewidth(lpbi); 

if(!PCXReadLine(linebuffer,fh,bytes)) { 

DestroyAllObj ects(BAD_READ,FALSE); 
return(NULL); 

} 

if(bits==l) hmemcpy(pd,linebuffer,bytes); 
else if(bits > 1 && bits <= 4) { 

if(pcx.bits==4 && pcx.colour_planes==l) 
hmemcpy(pd,linebuffer,bytes); 
else { 

for(j=0;j<width;++j) { 

ps=linebuffer; 
for(k=a=0;k<bits;++k) { 

if(ps[j»3] & masktable[j & 0x0007]) 
a ! = bittable[k] ; 
ps+=pcx.bytes_per_line; 

} 

PutChunkyPixel(pd,j,a); 

} 

} 

} 

else if(bits==8) hmemcpy(pd,linebuffer,bytes); 
else if(bits==24) { 
ps=linebuffer; 
for(j=0;j<width; ++j ) { 

pd[j *RGB_SIZE+WRGB_RED]=ps[j] ; 
pd[j*RGB_SIZE+WRGB_GREEN]= 

ps[RGB_GREEN*pcx.bytes_per_line+j]; 
pd[j *RGB_SIZE+WRGB_BLUE] = 

ps[RGB_BLUE*pcx.bytes_per_line+j]; 

} 

} 


} 

if(bits==l) GetMonoPalette(palette); 
else { 


if(bits==8 && pcx.version >= 5) { 

_llseek(fh,-769L,SEEK_END); 
if(getbyte(fh)==12) { 
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if(_lread(fh,palette,768) != 768) { 

DestroyAllObj ects(BAD_FILE,FALSE) ; 
return(NULL); 

} 

} else memcpy(palette,pcx.palette,48); 

} 

else if(pcx.version == 3) 

memcpy(palette,pcxpalette,48); 
else 

memcpy(palette,pcx.palette,48); 

} 

PutDibPalette((LPBITMAPINFO)lpbi,palette); 
DestroyAllObjects(NO_ERROR,TRUE); 
return(handle); 



} 

#undef DestroyAllObjects() 

#define DestroyAllObjects(err,success) {\ 

if(fh ! = -1) _lclose(fh);\ 

if(fh != -1 && !success) DeleteFile(path);\ 
if(linebuffer != NULL) FixedGlobalFree(linebuffer);\ 
if(lpbi != NULL) GlobalUnlock(handle);\ 
error=err;\ 

} 

DLL_EXPORT (WORD) WriteGraphicFile(LPSTR path, HANDLE handle) 

{ 

LPBITMAPINFOHEADER lpbi=NULL; 

PCXHEAD pcx; 

HPSTR ps; 

LPSTR linebuffer=NULL,extrabuffer=NULL; 

char palette[768]; 

unsigned int linewidth; 

int width,depth,bits; 

int a,i,j,k,fh=-l; 

if((fh=_lcreat(path,0))==-l) { 

DestroyAllObjects(BAD_CREATE,FALSE); 
return(FALSE); 

} 

if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(handle))==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(FALSE); 

} 

linewidth=LPBlinewidth(lpbi); 

if((linebuffer=FixedGlobalAlloc(linewidth+1024)) == NULL) { 
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DestroyAllObjects(BAD_ALLOC,FALSE); 
return(FALSE); 

} 

if((extrabuffer=FixedGlobalAlloc(linewidth+1024)) == NULL) { 

DestroyAllObjects(BAD_ALLOC,FALSE); 
return(FALSE); 

} 

width=(int)LPBwidth(lpbi); 

depths(int)LPBdepth(lpbi); 

bits=(int)LPBbits(lpbi); 

lmemset((LPSTR)&pcx,0,sizeof(PCXHEAD)); 

if(bits < 4) GetDibPalette((LPBITMAPINFO)lpbi,pcx.palette); 

if(bits==l) { 

pcx.manufacturer=10; 
pcx.encoding=l; 
pcx.xmin=pcx.ymin=0; 
pcx.xmax=width-1; 
pcx.ymax=depth-1; 
pcx.palette_type=l; 
pcx.bits=l; 
pcx.version=5; 
pcx.colour_planes=l; 

pcx.bytes_per_line=PIXELS2BYTES(width); 

} 

else if(bits > 1 && bits <=4) { 
pcx.manufacturer=10; 
pcx.encoding=l; 
pcx.xmin=pcx.ymin=0; 
pcx.xmax=width-l; 
pcx.ymax=depth-l; 
pcx.palette_type=l; 
pcx.bits=l; 
pcx.version=5; 
pcx.colour_planes=bits; 

pcx.bytes_per_line=PIXELS2BYTES(width); 

} 

else if(bits > 4 && bits <=8) { 

pcx.manufacturer=10; 
pcx.encoding=l; 
pcx.xmin=pcx.ymin=0; 
pcx.xmax=width-1; 
pcx.ymax=depth-l; 
pcx.palette_type=l; 
pcx.bits=8; 
pcx.version=5; 
pcx.colour_planes=l; 
pcx.bytes_per_line=width; 
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} 

else { 

pcx.manufacturer 10 ; 

pcx.encoding=l; 

pcx.xmin=0; 

pcx.ymin=0; 

pcx.xmax=width-1; 

pcx.ymax=depth-l; 

pcx.colour_planes=3; 

pcx.bytes_per_line=width; 

pcx.bits=8; 

pcx.version=5; 


if(bits <= 4) GetDibPalette((LPBITMAPINFO)lpbi,pcx.palette); 

if(_lwrite(fh,(LPSTR)&pcx,sizeof(PCXHEAD)) != 

sizeof(PCXHEAD)) { 

DestroyAllObj ects(BAD_WRITE / FALSE); 
return(FALSE); 


ps=LPBimage(lpbi)+(DWORD)LPBlinewidth(lpbi)*(DWORD)depth; 

resetbuffer(); 

for(i=0;i<depth;++i) { 

ps-=(DWORD)LPBlinewidth(lpbi); 

hmemcpy(linebuffer/ps,linewidth); 

if(bits==l) { 

if(!PCXWriteLine(linebuffer,fh,pcx.bytes_per_line)) { 
DestroyAllObjects(BAD_WRITE,FALSE); 
return(FALSE); 

} 

} 

else if(bits > 1 && bits <=4) { 

for(k=0;k<bits;++k) { 

for(j=0;j<width;++j ) { 

a=GetChunkyPixel(linebuffer,j); 
if(a & bittable[k]) 

extrabuffer[j>>3] != 

masktable[j & 0x0007]; 

else 

extrabuffer[j>>3] &= 

~masktable[j & 0x0007]; 

} 


if(!PCXWriteLine(extrabuffer,fh, 
pcx.bytes_per_line)) { 

DestroyAllObjects(BAD_WRITE,FALSE); 








\v* 
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return(FALSE); 

} 

} 

} 

else if(bits > 4 && bits <= 8) { 

if(!PCXWriteLine(linebuffer,fh, 
pcx.bytes_per_line)) { 

DestroyAllObjects(BAD_WRITE,FALSE); 
return(FALSE); 

} 

} 

else if(bits == 24) { 

for(j=0;j<width;++j) 

extrabuffer[j]=linebuffer[ j *RGB_SIZE+WRGB_RED] ; 
if(!PCXWriteLine(extrabuffer,fh, 
pcx.bytes_per_line)) { 

DestroyAllObjects(BAD_WRITE,FALSE); 
return(FALSE); 


for(j =0;j <width;++j) 

extrabuffer[j]=linebuffer[j *RGB_SIZE+WRGB_GREEN]; 
if(!PCXWriteLine(extrabuffer,fh, 
pcx.bytes_per_line)) { 

DestroyAllObjects(BAD_WRITE,FALSE); 
return(FALSE); 

} 


for(j=0;j<width;++j) 

extrabuffer[j]=linebuffer[j *RGB_SIZE+WRGB_BLUE]; 
if(!PCXWriteLine(extrabuffer,fh, 
pcx.bytes_per_line)) { 

DestroyAllObjects(BAD_WRITE,FALSE); 
return(FALSE); 


putbufferedbyte(EOF,fh); 

if(bits > 4 && bits <=8) { 

putbyte(12,fh); 

GetDibPalette((LPBITMAPINFO)lpbi,palette); 


if(_lwrite(fh,palette,768) != 768) { 

DestroyAllObjects(BAD_WRITE,FALSE); 
return(FALSE); 

} 

} 
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DestroyAllObjects(NO_ERROR,TRUE); 
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return(TRUE); 

} 

#undef DestroyAllObjects() 


DLL_EXPORT (WORD) GetError(LPSTR text) 

{ 

if(text != NULL) Istrcpy(text,GetErrorText(error)); 
return(error); 

} 

DLL_EXPORT (LPSTR) GetCopyright() 

{ 

return("Copyright \251 1995 Alchemy Mindworks Inc."); 

} 

DLL_EXPORT (LPSTR) GetNotice() 

{ 

return("PCX supports from one to 24 bits of colour.\n" 
"It was created by the ZSoft Corporation, and\n" 
"uses run-length compression. Nobody doesn't\n" 
"like PCX files."); 

} 


WORD PCXReadLine(LPSTR p,int fh,int bytes) 

{ 

int n=0, c, i; 


do { 

c=getbufferedbyte(fh); 
if(c==EOF) return(FALSE); 
if((c & OxcO) == OxcO) { 
i=c & 0x3 f; 

c=getbufferedbyte(fh); 
if(c==EOF) return(FALSE); 
while (i--) p[n++]=c; 

} 

else p[n++]=c; 

} while(n < bytes); 

if(n==bytes) return(TRUE); 
else return(FALSE); 


WORD PCXWriteLine(LPSTR p,int fh,int n) 

{ 

unsigned int i=0,j=0,t=0; 


do { 

i = 0 ; 

while((p[t+i]==p[t+i+1]) && ((t+i) < n) && (i < 63))++i; 
if (i>0) { 

if(putbufferedbyte(i ! OxcO,fh)==EOF) 
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return(FALSE); 

if(putbufferedbyte(p[t],fh)==EOF) 
return(FALSE); 
t+=i; 
j+=2; 

} 

else { 

if(((p[t]) & OxcO)==OxcO) { 

if(putbufferedbyte(Oxcl,fh)==EOF) 
return(FALSE); 

++j; 

} 

if(putbufferedbyte(p[t++],fh)==EOF) 
return(FALSE); 

++j ; 

} 

} while(t<n); 
return(TRUE); 

} 

The other mildly tricky aspect of reading a PCX file’s header is in 
locating its palette. This will be a default two-color palette with black 
for color 0 and white for color 1 if the file has 1 bit of color. It will be 
the 16 RGB color definitions in the header if the file has between 2 
and 4 bits of color unless the version number is 3, in which case it will 
be the default PCX palette. If there are 8 bits of color in a PCX file, 
the palette will be located at the end of the file, as has been previously 
discussed. Images with 24 bits of color don’t have palettes. 

The initial palette argument passed to CreateDIB is meaningless, as 
it’s a lot more convenient to sort out the palette of a PCX file after it 
has been completely decoded. You can see how the palettes are sorted 
out down near the end of ReadGraphicFile. The PutDibPalette 
function from WINBIT is used to store the palette in the device¬ 
independent bitmap created earlier in the function. 

The for loop in ReadGraphicFile gets to deal with all the really tricky 
elements of the myriad of PCX file types—including the illegal ones. It 
calls PCXReadLine, as discussed earlier, once for each line in the 
image. The number of lines in an image can be worked out from the 
image dimensions stored in the PCX file’s header. It then deals with 
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whatever line format conversion is required to get the PCX file’s 
bitmap lines into something Windows will like the taste of. 

Monochrome lines will emerge from PCXReadLine in the correct form 
and will not require any massaging. The same is true for lines of 8-bit 
pixels. Lines with between 2 and 4 bits of color that are stored as 
interleaved planes will require the most involved and time-consuming 
data manipulation. 

The ReadGraphicFile function can convert a planar line to a chunky 
pixel, Windows-style 4-bit image line by assembling pixel values from 
the bits of the consecutive planes. In order to ascertain the value of 
the pixel x in the 4-bit line at p, it must test p[x >> 3] & masktable 
[x & 7] four times, incrementing p by the width of one plane each 
time. 

The code in ReadFile that manages planar lines uses another table— 
this one called bittable. This is actually the inverse of masktable and 
provides the values to be added to a pixel for each successive plane 
being read. As such, if the first plane had its bit set, the pixel being 
read would be a I bittable[0]. If the second plane had its bit set the 
pixel would be a I bittable[l] and so on. 

The bittable object is defined in WINBIT.CPP. 

The planar line translation code isn’t necessary if the PCX file being 
read has chunky pixel lines to begin with, of course. This will be the 
case if pcx.bits holds 4 and pcx.color_planes holds 1, as has been 
discussed previously. In this case, the lines can be read from the file 
and written directly to the destination bitmap. 

The 24-bit line type also entails some juggling to co-exist with 
Windows. Once again, the ZSoft specification for the multiple-plane 
lines of a 24-bit PCX file isn’t all that clear as to whether each line 
should be compressed as three discrete 8-bit planes or as one long 
object containing the three initial planes. We’ll deal with this ambiguity 
the same way as we did the multiple planes of 16-color files; that is, by 
reading the whole line as a single field and then swabbing the 
individual bytes from the resulting morass of data. In this case, doing 
so doesn’t involve much of a speed penalty, as the bytes would have 







PCX files 


required swabbing in any case to get them into proper Windows RGB 
pixels. 

It’s worth noting that the lines read from a PCX file are written in 
inverse order in the destination device-independent bitmap. The 
pointer pd, where the lines will be written, begins by pointing to the 
last line in the bitmap, which is where the first line in the file will go. 
The pointer is then decremented by the number of bytes in a line with 
each iteration of the for loop. Keep in mind that Windows and OS/2 
device-independent bitmaps are stored upside down. 

The WriteGraphicFile function of PCXLIB.CPP does what 
ReadGraphicFile did, but in reverse. Fortunately, you needn’t deal 
with a lot of illegal file types in writing image files, and as such the 
code to write a file is usually a lot easier to work out. The large if else 
tree at the top of the function sets up the elements of the PCXHEAD 
object that will form the header of the file being written. 

Palettes must be handled in various ways in WriteGraphicFile, 
depending on what the color depth of the images is. If the image 
being written has 16 or fewer colors, the palette can be included in its 
PCXHEAD header. If it has 256 colors, the palette can be ignored 
until the entire image has been compressed. 

Once again, the planar lines of a 16-color PCX file and the chunky 
pixel lines of a device-independent bitmap require a bit of juggling to 
get them on speaking terms. In this case, the swabbing works just the 
opposite to the way it did in ReadGraphicFile. 

This version of WriteGraphicFile will not create the Windows-specific 
16-color PCX file type discussed earlier in this chapter, although the 
foregoing ReadGraphicFile function will read such files. You might 
want to modify WriteGraphicFile to do so if you anticipate creating 
PCX files that will not be leaving the narrow confines of Windows and 
OS/2 applications capable of dealing with them. Sneaking past the 
bitwise manipulation required to convert the 16-color line formats of 
outgoing PCX files will speed up the writing process considerably. 

The RGB pixels of a Windows bitmap must be split up into planes 
when 24-bit images are written with WriteGraphicFile. 





Finally, note that, when a complete 8-bit PCX image has been written 
to disk, WriteGraphicFile will write a 256-color palette at the end of 
the image data. 

The WriteGraphicFile function calls PCXWriteLine to actually 
compress line data. As run-length compression functions go, this one 
is agreeably simple. It works by counting repeating bytes until it 
encounters a byte that does not match the ones it has been counting 
or until it runs out of bytes to compress. Having fallen out of its loop, 
it checks to see if it has actually managed to count any bytes, writing a 
run of bytes field if it did. Otherwise, it writes the byte under 
consideration directly to the file and tries again. If the byte under 
consideration has its 2 high-order bits set, however, it writes it as a 1 
byte run; that is, it writes 0C1H and then the byte. 

The file handling in the ReadGraphicFile and WriteGraphicFile 
functions is a bit unusual. It uses the buffered file functions discussed in 
chapter 2 of this book. These behave a bit like the C language 
streamed file functions, except that they work considerably faster, 
albeit with much less flexibility. They also only allow a maximum of 
one file to be open at a time—hardly a problem for PCXLIB, which 
will only read or write one image at a time. It’s important to call 
resetbuffer before using the getbyte or putbyte functions and to call 
putbyte with an argument of EOF before closing a file that’s been 
written to using these functions. 

Once the entire image has been written by WriteGraphicFile, a 
256-color palette can be added to the end of the image data for files that 
require one. As the palette format used by PCX files is the same as that 
in which palette entries are stored by the other palette functions 
discussed in this book, writing a 256-color palette merely involves writing 
one byte with the value 12 and then 768 bytes of the palette itself. 


PCX files: 

history on your hard drive 


Supporting PCX files in your applications should avail you of the most 
universally accepted compatibility path for other graphic software at 







the moment. The catch to this is that PCX files are very retro and low 
tech, and they take up a lot of disk space. 

Having said all this, PCX support exists in more PC graphic 
applications than does support for any other single bitmapped image 
file format, and this is likely to remain so for some time. The PCX 
format also offers the combination of some compression, however 
ineffective it might be for scanned image types, and a full range of 
color depth options. 

One of the reasons that PCX support is likely to remain fairly 
common in PC software is that, as you’ll have seen in this chapter, 
PCX files are easy to work with. The code to read and create them is 
simple, and it doesn’t even require a lot of memory to work with, 
unlike the GIF format. 

It does seem fortunate, however, that PC display hardware seems to 
have arrived at a stable level of maximum color depth. It’s unlikely to 
have cause to exceed 24 bits in the immediate future. This might be a 
kindness to the PCX format, which doesn’t look like it could survive 
having one more addition bolted onto it. 
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HE creators of Windows, with somewhat more vision than the 
authors of Warp—or perhaps simply with better hindsight— 
realized that aside from being able to multitask, time slice, manage 
memory, apportion resources, and respond to messages, Windows 
had to look attractive before anyone would want to use it. 
Appreciating that the word “attractive” is a bit ambiguous, they built 
in features that would permit Windows’ users to define it for 
themselves. You can change the way the Windows desktop looks in all 
sorts of ways. One of the most interesting of these is inarguably the 
application of wallpaper. 

Wallpaper is Windows’ facility for replacing its default single-color 
desktop background with a bitmap or with a tiled array of bitmap 
fragments. Inasmuch as you can choose the bitmap you select as 
wallpaper, you can define how you want your desktop to appear. 
Figure 5-1 illustrates Windows with a single large bitmap as wallpaper 
and with a smaller image tiled across the desktop. 
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Continued. 

Despite the obvious utility of being able to look at lizards, barely 
clothed women, or fractals when you close an application, the 
bitmapped image format that Windows uses to store wallpaper has 
numerous other applications. It’s the default file format used by 
Windows Paint and many other Microsoft applications, and it serves as 
a really convenient way to get bitmapped images into your 
applications. This latter use will be dealt with in detail later in this 
chapter. 

The Windows BMP format has a number of singular characteristics. 
Specifically, it will store images with up to 24 bits of color and does so 
in a format that is identical to that of a Windows device-independent 
bitmap. In addition, BMP files are stored uncompressed. This means 
that you can load one into a Windows application and display it with 
an absolute minimum of time-consuming data manipulations. 


Figure 5-1 
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The principal advantage of the BMP format—that of being 
uncompressed and, as such, quick to read—is also one of its principal 
drawbacks. Bereft of the benefits of image compression, BMP files are 
usually pretty huge. You probably will not want to keep a lot of images 
in the BMP format hanging around on your hard drive. 

As an aside, the fact that BMP files are stored uncompressed will make 
them quicker to load in most applications. This might not be the case 
if you’ll be storing them on a relatively slow medium, such as floppy 
disks or CD-ROMs. In reading an image file from a CD-ROM, for 
example, the time it takes to decode compressed line data might be 
significantly less than the seek time for the drive itself. As such, 
reading relatively few bytes of compressed data from a slow device and 
then uncompressing it in software will usually take significantly less 
time than reading a lot of uncompressed data, even if the latter 
approach obviates the need for an unpacking function. 

As was touched on in chapter 1, as images get more complex, the 
ability of even the more sophisticated image file compression 
algorithms to make them smaller will diminish. If you anticipate doing 
a lot of work with scanned or dithered color images, you might well 
find that highly compressed formats such as PNG don’t really make 
your pictures significantly smaller, even though they do spend a pretty 
respectable amount of time trying. This will almost certainly be the 
case if you work with scanned true color pictures. Most attempts to 
compress these actually make them bigger. In this case, you might find 
that BMP files aren’t quite as wasteful of space as they seem. 

It’s probably worth mentioning that, while most Windows applications 
that work with bitmapped graphics will handle the BMP format, few 
DOS applications do. Those that will—such as the DOS version of the 
Graphic Workshop package included on the companion CD-ROM for 
this book—don’t read some types of BMP files particularly quickly, as 
the BMP data format is very much unlike the way images are typically 
stored for DOS applications. 

As with the internal device-independent bitmaps discussed in chapter 
2, BMP image data can contain pictures with 1, 4, 8, and 24 bits of 
color. If you wanted to store a picture with an intermediate number of 
colors in a BMP file, you would have to promote it to the next highest 









color depth and waste the intervening bits. The 1-, 4and 8-bit BMP 
formats include color palettes. High-end 24-bit BMP files don’t, as 
each pixel can specify its own RGB color. 

As with Windows’ internal bitmap structure, the images in BMP files 
are stored upside down—the first image line read from a BMP file will 
be the bottom line of the picture. 

Image lines in a BMP file are always padded out to end on an even 
word boundary. It’s important to keep this in mind, as odd size 
pictures that are decoded with line lengths calculated using 
pixels2bytes to work out their line lengths will list somewhat to port. 

The catch in all this simplicity is that, while both Windows and Warp 
support BMP files, the BMP files they support are slightly different. If 
you only work with BMP files created by applications running under 
your operating system—whether this is Windows or Warp—you’ll find 
that the internal structure of BMP files is agreeably predictable. 
Writing a BMP file reader that will read both types correctly is 
somewhat more involved. 


30 BMP file structure 


A BMP file will always begin with a header. Unfortunately, there are 
two possible header structures, depending upon the source of the 
BMP file. The most common is a Windows BITMAPINFOHEADER. As 
was touched on in chapter 1, it’s defined like this: 


typedef struct { 

DWORD biSize; 

LONG biWidth; 

LONG biHeight; 

WORD biPlanes; 

WORD biBitCount; 

DWORD biCompression; 
DWORD biSizelmage; 
LONG biXPelsPerMeter; 
LONG biYPelsPerMeter; 
DWORD biClrUsed; 

DWORD biClrlmportant; 
} BITMAPINFOHEADER; 



Alternately, a BMP file can begin with an OS/2 BITMAPINFOHEADER, 
or what Windows calls a BITMAPCOREHEADER. The version of it to 
be used in this chapter will be defined like this: 

typedef struct { 

DWORD bcSize; 
short int bcWidth; 
short int bcHeight; 

WORD bePlanes; 

WORD bcBitCount; 

} BITMAPCOREHEADER; 

You might well ask how an application might know which sort of the 
header it’s looking at when it opens a BMP file. This would seem like 
an important issue, as the headers are structured differently. The 
answer is not really documented in the Windows texts that deal with 
this subject, but you can work it out once you understand what the 
various fields in these headers do. 

The BITMAPINFOHEADER object is also used as the header for a 
device-independent bitmap under Windows. Earlier versions of OS/2 
used what they called a BITMAPINFOHEADER—and Windows calls a 
BITMAPCOREHEADER—in the same capacity. The current version of 
OS/2 uses a BITMAPINFOHEADER2, as dealt with in chapter 1. 

Whether a BMP file comes from a Windows or Warp application, it 
will precede its bitmap object with a BITMAPFILEHEADER object. 
Happily, this doesn’t change between operating systems. It looks like 
this: 


typedef struct { 

UINT bfType; 

DWORD bfSize; 

UINT bfReservedl; 

UINT bfReserved2; 

DWORD bfOffBits; 

} BITMAPFILEHEADER; 

The bfType field of a BITMAPFILEHEADER will always contain the 
string BM, which identifies the file as a genuine BMP file. Alternately, 
of course, it could just be a text file in which the first sentence begins 
with these two letters—Windows is fairly gullible at times. 






The bfSize field will be the total size of the BMP file in bytes, 
something that isn’t all that useful in decoding one. The bfOffBits 
element specifies the offset to the actual bitmap of the file. 

Having read the BITMAPFILEHEADER of a BMP file, the next four 
bytes will be the biSize field of its BITMAPINFOHEADER —or the 
bcSize field if it’s actually a BITMAPCOREPIEADER; that is, if the file 
has come from OS/2. This is what can be used to figure out the origin 
of a BMP file. It will be equal to sizeof(BITMAPINFOHEADER), if the 
file came from Windows, and sizeof(BITMAPCOREHEADER), if it 
hails from OS/2. The remainder of the header should be treated 
accordingly. 

Once you have decoded a BMP file’s header—whichever header it 
turns out to have—you should read the palette if it has one and then 
locate the image data itself. The BMP palette structure also varies with 
the type of header used. It will have 4 bytes per entry for Windows 
bitmaps and 3 bytes per entry for Presentation Manager bitmaps. The 
data is also ordered inconveniently. It appears in the order blue, 
green, and red, rather than the other way around. 

Having found the image data in a BMP file, all the work is very nearly 
done. In all four of the supported color depths of BMP files, the data 
will read from the file exactly as it should be structured to display it 
under Windows. 

Writing a BMP file is also agreeably simple. While you can use either 
header structure in theory, choosing the one that corresponds to the 
environment your applications will be running in is likely to present 
users of the files they create with the fewest compatibility problems. 
Surprisingly, some Windows applications and some of the Windows 
GDI calls that accept device-independent bitmaps will deal with either 
type—the same is not true under OS/2, which really wants to see a 
BITMAPINFOHEADER2 object at the beginning of all its device¬ 
independent bitmaps. 

Thus far I’ve discussed BMP files that are stored uncompressed. If you 
read the detailed discussion of device-independent bitmaps in chapter 
1 very carefully, you’ll probably recall that a BITMAPINFOHEADER 
includes a field that specifies how a line should be compressed. This 
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field is usually set to zero, meaning that no compression is to be used. 
It can also be set to one of two other values, defined as BI_RLE4 and 
Bi_RLE8. These define the image data in a BMP as having been 
compressed using a very simple run-length encoding scheme not 
unlike the one used by PCX files. 

In the dark days of Windows 3.1, a compressed BMP file was always 
stored using the extension RLE, making such files easy to spot. 
Gradually, third-party applications that created BMP files began using 
this compression, and as such a fully capable BMP reader should be 
able to deal with it. In fact, the Windows run-length encoding is 
awkward without being particularly effective in compensation. It was 
originally intended for use in a specific circumstance: replacing the 
Windows start-up bitmap for Windows 3.1 with a custom graphic. As 
such, like PCX run-length encoding, it was designed to be fast when 
it’s used with drawn images. It falls apart pretty readily if it’s asked to 
compress photorealistic images. 

Run-length encoding only exists for 4- and 8-bit bitmaps stored in 
BMP files. I should also note that the run-length decoder in the 
BMPLIB library, to be dealt with in a moment, only implements line- 
at-a-time decoding. One of the peculiarities of Windows’ RLE decoding 
is that it includes tokens to omit portions of a bitmap if no detail exists 
in them. Because these tokens are not recognized by BMPLIB, it will 
not correctly decode files that use them. As of this writing, there’s only 
one file you’re likely to encounter that does, this being the 
VGALOGO.RLE file that comes with some versions of Windows 3.1. It 
contains the default start-up Windows logo. 

As an aside, while not all Windows functions that deal with BMP files 
will read them when they’ve had their image data compressed, the 
Windows wallpaper manager will. 

The BMPLIB library 

Were it not for the prospect of having to deal with both Windows and 
OS/2 BMP files and with the occasional compressed BMP file, a BMP 
reader and writer would be agreeably trivial. You can read a BMP file 






by skipping past its BITMAPFILEHEADER object and reading the rest 
of the file into a buffer. Writing one involves little more—create a 
suitable BITMAPFILEHEADER object, write it to the destination file, 
and then write the contents of the source device-independent bitmap 
right after it. 

If you’re working with the Warp version of BMPLIB, note that a few 
of the object names have been changed a bit to avoid conflict with 
Warp’s defined objects. For example, a Windows 
BITMAPINFOHEADER and a Warp BITMAPINFOHEADER are 
different—the Warp version of BMPLIB uses a private name for the 
former. 


The complete source code for BMPLIB.CPP can be found in Fig. 5-2. 


/* 


BMP Library 

Copyright (c) 1995 Alchemy Mindworks Inc. 

*/ 

#include <windows.h> 

#include <stdio.h> 

#include <string.h> 

#include <stdlib.h> 

#include "winbit.h" 

HANDLE hlnst; 

WORD BMPgetrle4(LPSTR p,int fh,int bytes); 

WORD BMPgetrle8(LPSTR p,int fh,int bytes); 

WORD error=NO_ERROR; 

#ifdef _WIN32_ 

#pragma argsused 

DLL_EXPORT (BOOL) DllEntryPoint(HINSTANCE hlnstance, 
DWORD wDataSeg,LPVOID lpCmdLine) 

{ 

hlnst=hlnstance; 
return(TRUE); 

} 

#else 


Figure 5-2 



The source code for BMPLIB.CPP. 
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Figure 5-2 Continued. 

#pragma argsused 

DLL_EXPORT (int) LibMain(HANDLE hlnstance, 

WORD wDataSeg,WORD wHeapSize, LPSTR lpCmdLine) 

; { 

hlnst=hlnstance; 

if (wHeapSize > 0) UnlockData(0); 
return(TRUE); 

} 

#pragma argsused 

DLL_EXPORT (int) WEP(int nParameter) 

i ( 

return (TRUE); 

} 

#endif' 


DLL_EXPORT (LPSTR) GetFileExtension() 

{ 

return("BMP"); 

} 

DLL_EXPORT (WORD) GetLibraryVersion() 

{ 

return((VERSION « 8) ! SUBVERSION); 

} 

#define DestroyAllObjects(err,success) {\ 

if(fh != -1) _lclose(fh);\ 

if(!success && handle != NULL) GlobalFree(handle);\ 
error=err;\ 

} 

DLL__EXPORT (HANDLE) GetFilelnf ormation (LPSTR path) 

{ 

HANDLE handle=NULL; 

BITMAPFILEHEADER fileheader; 

BITMAPCOREHEADER coreheader; 

BITMAPINFOHEADER infoheader; 

RGBTRIPLE rgbtriple; 

RGBQUAD rgbquad; 
char palette[768]; 
long 1; 

unsigned int width,depth,bits; 
unsigned int i,n; 
int fh; 

Initialize(); 

if((fh=_lopen(path,OF_READ))==-l) { 

DestroyAllObjects(BAD_OPEN,FALSE); 
return(NULL); 


} 
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Continued. 

if(_lread(fh,(LPSTR)&fileheader 7 sizeof(BITMAPFILEHEADER)) != 

sizeof(BITMAPFILEHEADER)) { 

DestroyAllObjects(BAD_READ,FALSE); 
return(NULL); 

} 

if(fileheader.bfType != 'BM') { 

DestroyAllObjects(BAD_FILE,FALSE); 
return(NULL); 

} 


_lread(fh,(LPSTR)&1,sizeof(long)); 

_llseek(fh,(long)sizeof(BITMAPFILEHEADER),SEEK_SET); 

if(l==sizeof(BITMAPCOREHEADER)) { 

if(_lread(fh,(LPSTR)&coreheader, 
sizeof(BITMAPCOREHEADER)) != 

sizeof(BITMAPCOREHEADER)) { 

DestroyAllObjects(BAD_READ,FALSE); 
return(NULL); 

} 

width=(unsigned int)coreheader.bcWidth; 
depth=(unsigned int)coreheader.bcHeight; 
bits=(unsigned int)coreheader.bcBitCount; 

if(bits <= 8) { 

n=l«bits ; 
for(i=0;i<n;++i) { 

if(_lread(fh,(LPSTR)&rgbtriple, 
sizeof(RGBTRIPLE)) != 

sizeof(RGBTRIPLE)) { 

DestroyAllObjects(BAD_READ,FALSE); 
return(NULL); 

} 

palette[i*RGB_SIZE+RGB_RED]= 
rgbtriple.rgbtRed; 
palette[i*RGB_SIZE+RGB_GREEN]= 
rgbtriple.rgbtGreen; 
palette[i*RGB_SIZE+RGB_BLUE]= 
rgbtriple.rgbtBlue; 

} 

} 

} 

else if(l==sizeof(BITMAPINFOHEADER)) { 

if(_lread(fh,(LPSTR)&infoheader, 
sizeof(BITMAPINFOHEADER)) != 

sizeof(BITMAPINFOHEADER)) { 

DestroyAllObjects(BAD_READ,FALSE); 
return(NULL); 
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} 







Figure 5-2 Continued. 

widths(unsigned int)infoheader.biWidth; 
depth=(unsigned int)infoheader.biHeight; 
bits=(unsigned int)infoheader.biBitCount; 

if(bits <= 8) { 

n=l<<bits; 
for(i=0;i<n;++i) { 

if(_lread(fh,(LPSTR)krgbquad, 
sizeof(RGBQUAD)) != 

sizeof(RGBQUAD)) { 

DestroyAllObj ects(BAD_READ,FALSE) ; 
return(NULL); 



palette[i*RGB_SIZE+RGB_RED]= 
rgbquad.rgbRed; 

palette[i*RGB_SIZE+RGB_GREEN]= 
rgbquad.rgbGreen; 
palette[i*RGB_SIZE+RGB_BLUE]= 
rgbquad.rgbBlue; 

} 

} 

} 

else { 

DestroyAllObj ects(BAD_FILE,FALSE) ; 

return(NULL); 


} 


if((handle=CreateDibHeader(width,depth, 
palette,bits))==NULL) { 

DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

} 


DestroyAllObjects(NO_ERROR,TRUE); 
return(handle); 


#undef DestroyAllObj ects() 

#define DestroyAllObjects(err,success) {\ 

if(fh != -1) _lclose(fh);\ 
if(lpbi != NULL) GlobalUnlock(handle);\ 
if(linebuffer != NULL) FixedGlobalFree(linebuffer);\ 
if([success && handle != NULL) GlobalFree(handle);\ 
error=err;\ 

} 

DLL_EXPORT (HANDLE) ReadGraphicFile(LPSTR path) 

{ 

HANDLE handle=NULL; 

LPBITMAPINFOHEADER lpbi=NULL; 

BITMAPFILEHEADER fileheader; 







Continued. 

BITMAPCOREHEADER coreheader; 

BITMAPINFOHEADER infoheader; 

RGBTRIPLE rgbtriple; 

RGBQUAD rgbquad; 

LPSTR linebuffer=NULL; 

HPSTR ps; 

char palette[768]; 
long 1; 

unsigned int width,depth,bits,bytes; 
unsigned int i,n; 
int fh; 

Initialize(); 

memset((char *)kinfoheader,0,sizeof(BITMAPINFOHEADER)); 

if((fh=_lopen(path,OF_READ))==-l) { 

DestroyAllObj ects(BAD_OPEN,FALSE) ; 
return(NULL); 

} 

if(_lread(fh,(LPSTR)&fileheader, 
sizeof(BITMAPFILEHEADER)) != 

sizeof(BITMAPFILEHEADER)) { 

DestroyAllObjects(BAD_READ,FALSE); 
return(NULL); 

} 

if(fileheader.bfType != 'BM') { 

DestroyAllObjects(BAD_FILE,FALSE); 
return(NULL); 

} 

_lread(fh,(LPSTR)&1,sizeof(long)); 

_llseek(fh,(long)sizeof(BITMAPFILEHEADER),SEEK_SET); 

if(l==sizeof(BITMAPCOREHEADER)) { 

if(_lread(fh,(LPSTR)&coreheader, 
sizeof(BITMAPCOREHEADER)) != 

sizeof(BITMAPCOREHEADER)) { 

DestroyAllObjects(BAD_READ,FALSE); 
return(NULL); 

} 

width=(unsigned int)coreheader.bcWidth; 
depth=(unsigned int)coreheader.bcHeight; 
bits=(unsigned int)coreheader.bcBitCount; 

if(bits <= 8) { 

n=l<<bits; 
for(i=0;i<n;++i) { 

if(_lread(fh,(LPSTR)&rgbtriple. 
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sizeof(RGBTRIPLE)) != 

sizeof(RGBTRIPLE)) { 

DestroyAllObj ects(BAD_READ,FALSE) ; 
return(NULL); 


palette[i*RGB_SIZE+RGB_RED]= 
rgbtriple.rgbtRed; 
palette[i*RGB_SIZE+RGB_GREEN]= 
rgbtriple.rgbtGreen; 
palette[i*RGB_SIZE+RGB_BLUE]= 
rgbtriple.rgbtBlue; 

} 

} 

} 

else if(l==sizeof(BITMAPINFOHEADER)) { 

if(_lread(fh,(LPSTR)&infoheader, 
sizeof(BITMAPINFOHEADER)) != 

sizeof(BITMAPINFOHEADER)) { 

DestroyAllObjects(BAD_READ,FALSE); 
return(NULL); 

} 

width=(unsigned int)infoheader.biWidth; 
depth=(unsigned int)infoheader.biHeight; 
bits=(unsigned int)infoheader.biBitCount; 

if(bits <= 8) { 
n=l«bits ; 
for(i=0;i<n;++i) { 

if(_lread(fh,(LPSTR)&rgbquad, 
sizeof(RGBQUAD)) != 

sizeof(RGBQUAD)) { 

DestroyAllObjects(BAD_READ,FALSE); 
return(NULL); 

} 


} 

else 


palette[i*RGB_SIZE+RGB_RED]= 
rgbquad.rgbRed; 

palette[i*RGB_SIZE+RGB_GREEN]= 
rgbquad.rgbGreen; 
palette[i*RGB_SIZE+RGB_BLUE]= 
rgbquad.rgbBlue; 

} 

} 

{ 

DestroyAllObjects(BAD_FILE,FALSE); 
return(NULL); 


} 

if((handle=CreateDib(width,depth,palette,bits))==NULL) { 
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DestroyAllObj ects(BAD_ALLOC / FALSE) ; 
return(NULL); 


if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(handle)) == NULL) 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 


if((linebuffer=FixedGlobalAlloc 

(LPBlinewidth(lpbi)+1024))==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 


ps=LPBimage(lpbi); 

if(infoheader.biCompression ! = BI_RGB) 
resetbuffer(); 

bytes=WIDTHBYTES(LPBwidth(lpbi)*8) ; 

for(i=0;i<depth;++i) { 

if(infoheader.biCompression == BI_RGB) { 

if(_lread(fh / linebuffer,LPBlinewidth(lpbi)) != 

LPBlinewidth(lpbi)) { 

DestroyAllObjects(BAD_READ,FALSE); 
return(NULL); 

} 

} 

else if(infoheader.biCompression == BI_RLE4) { 
if(!BMPgetrle4(linebuffer,fh,bytes)) { 

DestroyAllObjects(BAD_READ,FALSE); 
return(NULL); 

} 

} 

else if(infoheader.biCompression == BI_RLE8) { 
if(!BMPgetrle8(linebuffer,fh,bytes)) { 

DestroyAl10bjects(BAD_READ,FALSE); 
return(NULL); 

} 

} 

else { 

DestroyAllObjects(BAD_FILE,FALSE); 
return (NULL) ; 

} 

hmemcpy(ps,linebuffer,LPBlinewidth(lpbi)); 
ps+=(DWORD)LPBlinewidth(lpbi); 


DestroyAllObjects(N0_ERR0R,TRUE); 
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return(handle); 

} 

#undef DestroyAllObjects() 

#define DestroyAllObjects(err,success) {\ 

if(fh != -1) _lclose(fh);\ 

if(fh != -1 && !success) DeleteFile(path);\ 
if(lpbi != NULL) GlobalUnlock(handle);\ 
error=err;\ 

} 

DLL_EXPORT (WORD) WriteGraphicFile(LPSTR path, HANDLE handle) 

{ 

BITMAPFILEHEADER fileheader; 

LPBITMAPINFOHEADER lpbi=NULL; 

HPSTR ps; 

LPSTR p; 

unsigned int linewidth,n; 
int i,fh=-1; 

InitializeO; 

if((fh=_lcreat(path,0))==-l) { 

DestroyAllObj ects(BAD_CREATE,FALSE); 
return(FALSE); 

: } 

memset((char *)&fileheader,0,sizeof(BITMAPFILEHEADER)); 
fi1eheader.bfType= 1 BM 1 ; 

if(_lwrite(fh,(LPSTR)&fileheader,sizeof(BITMAPFILEHEADER)) 
sizeof(BITMAPFILEHEADER)) { 

DestroyAllObjects(BAD_WRITE,FALSE); 
return(FALSE); 

i } 

if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(handle))==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(FALSE); 

} 

linewidth=LPBlinewidth(lpbi); 

if(_lwrite(fh,(LPSTR)lpbi,sizeof(BITMAPINFOHEADER)) != 

sizeof(BITMAPINFOHEADER)) { 

DestroyAllObjects(BAD_WRITE,FALSE); 

! return(FALSE); 

| ) 

if(LPBbits(lpbi) <= 8) { 

: p=(LPSTR)(lpbi)+lpbi->biSize; 
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n=sizeof(RGBQUAD)*(l<<LPBbits(lpbi)); 
if(_lwrite(fh,p,n) ! = n) { 

DestroyAllObjects(BAD_WRITE,FALSE); 
return(FALSE); 

} 

} 

fileheader.bfOffBits=_llseek(fh,OL,SEEK_CUR);; 

ps=LPBimage(lpbi); 

for(i=0;i<LPBdepth(lpbi);++i) { 

if(_hwrite(fh,ps,linewidth) != linewidth) { 
DestroyAllObjects(BAD_WRITE,FALSE); 
return(FALSE); 

} 

ps+=(DWORD)LPBlinewidth(lpbi); 

} 

fileheader.bfSize=_llseek(fh,OL,SEEK_CUR);; 

_llseek(fh,OL,SEEK_SET); 

if(_lwrite(fh,(LPSTR)&fileheader, 
sizeof(BITMAPFILEHEADER)) != 

sizeof(BITMAPFILEHEADER)) { 

DestroyAllObjects(BAD_WRITE,FALSE); 
return(FALSE); 

} 

DestroyAllObjects(NO_ERROR,TRUE); 
return(TRUE); 

} 

#undef DestroyAllObjects() 

DLL_EXPORT (WORD) GetError(LPSTR text) 

{ 

if(text != NULL) Istrcpy(text,GetErrorText(error)); 
return(error); 

} 

DLL_EXPORT (LPSTR) GetCopyright() 

{ 

return("Copyright \251 1995 Alchemy Mindworks Inc."); 

} 

DLL_EXPORT (LPSTR) GetNotice() 

{ 

return( 

"BMP is the common image file format for Microsoft\n" 
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"Windows and IBM OS/2 Warp... sort of. It supports\n" 

"up to 24 bits of colour. It uses no compression\n" 

"most of the time and run-length compression now\n" 

"and again.\n\n" 

"The Microsoft version of the BMP format can be easily\n" 
"identified by observing that images stored in it will\n" 
"always appear a year late, accompanied by an advertising^" 
"agency the size of Mars to the sound of an old Stones\n" 

"tune.\n\n" 

"The Warp version of the BMP format is characterized by\n" 
"its whispered discussion amongst nuns and South American\n" 
"explorers. It prefers grey-scale pictures."); 

} 

WORD BMPgetrle8(LPSTR p,int fh,int bytes) 

{ 

int a,c,i=0, j , n; 
lmemset(p,0,bytes); 
for(;;) { 

if((n=getbufferedbyte(fh)) == 0) { 

if((a=getbufferedbyte(fh))==EOF) 
return(FALSE); 


if(a==0) return(TRUE); 
else if(a==l) { 

if(i==bytes) return(TRUE); 
else return(FALSE); 

} 

else if(a==2) { 

getbufferedbyte(fh); 
getbufferedbyte(fh); 
continue; 

} 

j=a; 

while (a—) { 

if((c=getbufferedbyte(fh))==EOF) 
return(FALSE); 
if(i < bytes) p[i]=c; 

++i; 

} 

if(j & 1) getbufferedbyte(fh); 

} 

else { 

if(n==EOF) return(FALSE); 
if((a=getbufferedbyte(fh)) == EOF) 
return(FALSE); 
while (n—) { 








Continued. 

if (i < bytes) p[i]=a; 
++i ; 


WORD BMPgetrle4(LPSTR p,int fh,int bytes) 

{ 

int a, c=0, i=0,j,n; 
lmemset(p,0, (bytes»l) ) ; 
for(;;) { 

if((n=getbufferedbyte(fh)) == 0) { 

if((a=getbufferedbyte(fh)) == EOF) 
return(FALSE); 
if(a==0) return(TRUE); 
else if(a==l) { 

if(i==bytes) return(TRUE); 
else return(FALSE); 

> 

else if(a==2) { 

getbufferedbyte(fh); 
getbufferedbyte(fh); 
continue; 

} 

j=a»l ; 

while(a--) { 

if(i < bytes) { 

if (i & 1) p [i»l] != (c & 0x0f) ; 

else { 

if((c=getbufferedbyte(fh))==EOF) 
return(FALSE); 
p[i»l] != (c Sc OxfO) ; 

} 

} 

+ + i ; 

} 

if(j & 1) getbufferedbyte(fh); 

} 

else { 

if((a=getbufferedbyte(fh))==EOF) 
return(FALSE); 
while(n--) { 

if(i < bytes) { 

if(i & 1) p[i»l] != (a & OxOf) ; 
else p[i»l] != (a & OxfO) ; 

} 
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+ + l; 



} 


} 


It’s pretty easy to see what the ReadGraphicFile function in BMPLIB is 
up to—if you’ve been following the tales of headers and such thus far, 
this function can be seen as the whole works translated into C. It begins 
by opening the source file and reading its BITMAPFILEHEADER object. 
If the bfType field is BM, it can proceed to figure out which header 
comes next. If it’s something else, the function returns a NULL handle. 

There are various ways to deal with figuring out which header a BMP 
file has—the one that’s used here involves reading the 4 bytes after 
the BITMAPFILEFIEADER into a long integer and then seeking back 
by 4 bytes. The value in the long integer—presumably either 
sizeof(BITMAPINFOHEADER) or sizeof(BITMAPCOREHEADER)— 
will determine what ReadGraphicFile should do next. 

Note that it’s important to check for the presence of a palette by 
testing the bit depth, rather than simply reading 1 << bits entries. 

This works in a 16-bit environment, as 1 << 24 is too large to fit in a 
16-bit int and as such evaluates out to zero. It will crash a 32-bit 
application—1 << 24 does fit in a 32-bit int, but a 24-bit image does 
not have 16,777,216 palette entries. 

The ReadGraphicFile insists on the size value of the 
BITMAPINFOPIEADER being one of the aforementioned values— 
which should deal with the possibility of its being asked to read some 
other sort of file that just happens to start with the letters BM. 

Once the header has been unpacked, ReadGraphicFile calls 
CreateDIB to return a handle to a suitable device-independent bitmap 
and then unpacks the image data. If the image lines are 
uncompressed, they can be read into the device-independent bitmap 






directly, a procedure that is blindingly fast. Computers are good at 
doing almost nothing in almost no time. Compressed lines must be 
read 1 byte at a time—in this case, the resetbuffer function in 
WINBIT is called, and the rest of the file is read through 
getbufferedbyte. 

You can see the BMPgetrle4 and BMPgetrle8 functions to read run- 
length encoded lines at the bottom of the BMPLIB.CPP file. There’s a 
complete discussion of how Windows’ run-length encoding works in 
the Windows Software Development Kit documentation, should you 
care to get up close and personal with them—in most cases, you can 
safely ignore them. 

Writing a BMP file is equally simple. The BMPLIB library writes BMP 
files native to the environment it’s being used in; that is, the Windows 
version will write Windows BMP file, and the Warp version will write 
OS/2 BMP files. You can easily modify this if you need the ability to 
create both types of files. 

The WriteGraphicFile function begins by creating the destination file 
and writing a BITMAPFILEHEADER object to it. It then writes a 
suitable device-independent bitmap header to the file. The 
WriteGraphicFile only writes uncompressed BMP files, so it has no 
need to worry about figuring out the file size. It writes a list of palette 
objects to files that require them, and then writes the image data itself. 
In this example, it writes the image lines one line at a time—in fact, it 
could write the whole image buffer at once. 

I ^1 Using BMP files 

The applications for BMP files and some of the things you can derive 
from them are far more interesting than the rather pedestrian BMP 
format itself. This section will discuss the use of BMP images and 
bitmaps as Windows resources. The code to be dealt with here will 
allow you to apply bitmaps to your own applications, having them 
appear almost anywhere you want. You’ll probably have seen bitmaps 
used in these contexts before and not thought much about them. If 
you’ve explored the Graphic Workshop for Windows package on the 
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companion CD-ROM for this book, you’ll have seen them as the 
buttons in its tool bar and as the unicorn in its About box. 

There are two specific aspects of bitmaps to deal with if you’d like to 
use them in these sorts of situations—specifically, you’ll have to learn 
how to store them in a resource script and then how to actually make 
them appear in your applications. Neither of these things is 
particularly difficult—but neither works quite as it might seem, either. 

This section will discuss using bitmap objects in Windows applications 
only—there is no corresponding source code for OS/2 on the 
companion CD-ROM. 

Figure 5-3 illustrates the BMPTOYS application. This is Windows 
software at its best. It does nothing and does a really good job of it. 

There are a number of noteworthy elements in BMPTOYS, and while 
reproducing them as they appear here will have your software 
denounced as subversively tacky, the techniques involved in making 
BMPTOYS as tacky as it is will prove useful in other, less extreme 
contexts. 

The BMPTOYS window will be found to have a number of unusual 
elements, to wit: 

^ The background is neither gray nor tiny green bricks, but rather 
a pattern of fake leopard spots. It could have been cubic 
zirconia. 

There’s a tool bar with aviatorial reptiles in the buttons. 

Actually, most lizards are capable of flight if you drop them from 
a high enough place. At the very least, they’ll make a serious 
effort to learn. 

There’s another lizard in the System menu, as the About item. 

Each of the bitmap items in BMPTOYS is stored as a BMP file. While 
it would be possible to store these BMP files as discrete entities on 
disk, Windows offers a much better way to handle them. They can be 
incorporated into the BMPTOYS.EXE file as resources. 






. 




dealing into the Ok button at the sound of the tone Be sure to state your fuB name. age. 
weight, eve colour, bc& temperature in degrees Kelvin, dde of birth. mother's maiden 

ft §i|ipi!iii§iitp§iii^ 

'about sending foreign aid to extraterrestrials, number of vampire lemmings in your family. 

■ -lehderioSoward feenfe'wh^'ftftfihedb 3srft#snported carftth a Bye ,feo& , 
constrictor, union status, the last stance when you attempted to mail a kayak and the 
nature of your need for help. You have seven seconds. 


Thanknow !a clcfcfi^g ortOk ^^ 


The BMPTOYS application, heapin’ lizards, 
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A Windows EXE file is a very complex entity. When it’s executed, 
some of it will be loaded into memory and run, but in most cases, the 
bulk of the file will remain on disk and only be loaded when it’s 
required. This includes chunks of infrequently used code and all sorts 
of data elements. The latter are what Windows refers to as resources. 

Windows resources include things like menus, dialogs, icons, 
accelerator tables, and bitmaps. They are called for when they’re 
needed and are used and discarded—it all sounds like the plot of an 
HBO movie. Unlike what appears on HBO, however, discarded 
resources never come back in an uncontrollable rage and bludgeon 
your application to death with a sack of ferrets. 

You will no doubt have dealt with resources to some extent through 
the Resource Workshop application included with Borland C++, or 
through its equivalent under other development environments. It’s all 
but impossible to create a Windows application without defining a few 

















resources. What might be less than obvious about the RC files that 
Resource Workshop creates, however, is that they’re simple text files. 
You can open one in the Borland C++ editor and add to it. This is 
handy for fine-tuning things in dialogs and menus, to be sure—it also 
allows you to insert new resource definitions. 

Here’s an example of the resource script declaration for a bitmap. 

This defines the tacky fake leopard spots bitmap to be used as the 
background for the BMPTOYS main window: 

BackgroundBrush BITMAP "bmptoys1.bmp" 

This line causes Borland C++ to create a BITMAP resource called 
BackgroundBrush that contains the contents of BMPTOYSl.BMP 
when it compiles BMPTOYS.RC. This resource can subsequently be 
loaded with the LoadResource or LoadBitmap functions. 

The same Windows GDI calls that are used to display device¬ 
independent bitmaps returned by the graphic format libraries can be 
used to deal with bitmaps loaded as resources. In fact, there are a few 
additional complexities involved in using bitmaps as they appear in 
BMPTOYS. 

Figure 5-4 illustrates the complete source code for BMPTOYS.CPP. 

Let’s begin by looking at how the leopard spot window background is 
drawn. It’s worth noting that the basis of this effect is a relatively small 
bitmap—it is, however, one that has been crafted to create a repeating 
pattern when it’s tiled. Filling the main window of BMPTOYS with 
multiple instances of it results in the appearance of a large, complex 
background image. You can find quite a few bitmaps suitable for use as 
tiles in the \ WINDOWS directory of your system. 

The background bitmap is handled by the TileWindow function in 
BMPTOYS.CPP. You can find this near the middle of the file. It 
illustrates how to load and display a bitmap stored in an application’s 
resource file. 
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/* 


BMP Toys 

Copyright (c) 1995 Alchemy Mindworks Inc. 


*/ 


#include 
#include 
#include 
#include 
#include 
#include 
#include 


<windows.h> 
<stdio.h> 
<stdlib.h> 
cctype.h> 
<string.h> 
<commdlg.h> 
"winbit.h" 


#ifdef _WIN32_ 

#define SetWindowOrg(hdc,x,y) SetWindowOrgEx(hdc,x,y,NULL) 

#define MoveTo(hdc,x,y) MoveToEx(hdc, x, y,NULL) 

#endif 


#define FILE_OPEN 101 
#define FILE_SAVEAS 102 
#define FILE_GETINFO 103 
#define FILE_PRINT 104 
#define FILE_NOTICE 105 

#define FILE_CLOSE 106 
#define FILE_EXIT 199 

#define EDIT_CUT 201 
#define EDIT_COPY 202 
#define EDIT_PASTE 203 

#define HELPM_INDEX 901 
#define HELPM_U S ING 902 
#define HELPM_ABOUT 999 

#define APPLICATION "BmpToys" 


#ifdef IDHELP 
#undef IDHELP 
#endif 


#define IDHELP 998 
#define IDEXIT 101 
#define IDABOUT 301 

#define BUTTON_WIDE 96 
#define BUTTON_DEEP 72 
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The BMPTOYS.CPP source code. Spot the lizards. . . . 
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; #define OK_MESSAGE \ 

"Thank you for clicking on Ok.\n\n"\ 

"This button doesn't do anything, but "\ 

"in an effort to be politically correct "\ 

"we've tried to make sure it doesn't "\ 

"offend anyone while it's busy not doing "\ 

"it. No fur-bearing animals were "\ 

"trapped or raised in captivity to "\ 

"create this button." 

#define CANCEL_MESSAGE \ 

"Thank you for clicking on Cancel.\n\n"\ 

"This button has initiated the end of the "\ 

"universe as we know it. In a few moments "\ 

"the fabric of reality will begin to "\ 

"spontaneously unravel and the atomic "\ 

"cohesion of matter will disintegrate. "\ 

"Life will become impossible at about "\ 

"2:35pm next Tuesday and physical laws "\ 

"will no longer be applicable west of "\ 

"the Rockies. All purchases will become "\ 

"subject to a 5 percent surcharge if they're "\ 

"red. No persons under the age of 18 will "\ 

"be admitted without an adult or a live "\ 

"grizzly bear. Stamps will no longer be "\ 

"accepted in place of cash. Pigs will not "\ 

"only fly -- they'll enjoy it.\n\n"\ 

"Have a nice eternity." 

#define HELP_MESSAGE \ 

"Thank you for clicking on Help.\n\n"\ 

"Sadly, no help is available at this time. "\ 

"If you are urgently in need of help, please "\ 

"speak clearing into the Ok button at the "\ 

"sound of the tone. Be sure to state your "\ 

"full name, age, weight, eye colour, body "\ 
"temperature in degrees Kelvin, date of birth, "\ 
"mother's maiden name, country of origin, "\ 

"innoculation status, whether you will visit "\ 

"a farm in the next 14 days, number of "\ 

"dependent children under the age of 60, "\ 

"marital status, allergies, feelings about "\ 

"sending foreign aid to extraterrestrials, "\ 

"number of vampire lemmings in your family, "\ 
"tendency toward dimentia when confined in a "\ 

"small imported car with a live boa constrictor, "\ 
"union status, the last instance when you attempted "\ 
"to mail a kayak and the nature of your need for "\ 
"help. You have seven seconds." 



#define ABOUT_MESSAGE\ 

"BmpToys with Reptiles "\ 


•v *•< 
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"Copyright \251 1995 Alchemy Mindworks Inc.\n\n"\ 
"Contains no polysorbate 80 or tropical oils. "\ 

"Recycle where required by law. Not for use "\ 

"by children or liberals. Not recommended for "\ 
"fuel-injected engines. For more information "\ 

"contact 1-80O-CAT-FOOD." 

LRESULT FAR PASCAL SelectProc(HWND hwnd,unsigned int message, 
WPARAM wParam, LPARAM lParam); 

int CreateMainWindow(HANDLE hlnstance,HANDLE hPrevInstance, 
LPSTR IpszCmdParam,int nCmdShow); 
int DrawBitmapButton(HWND hwnd,WORD message,WORD wParam, 

LONG lParam,WORD id) ; 

WORD TileWindow(HWND hwnd,HDC hdc,LPSTR bitmap); 

void Drawlmage(HDC hdc,WORD x,WORD y,HBITMAP image,DWORD op); 

void CentreWindow(HWND hwnd); 

void DoMessage(HWND hwnd,LPSTR message); 

char s zAppName[]=APPLICATION; 

char filename[STRINGSIZE+1]; 

HANDLE hlnst; 

#pragma warn -par 

int PASCAL WinMain (HANDLE hlnstance,HANDLE hPrevInstance, 
LPSTR IpszCmdParam,int nCmdShow) 

{ 

hlnst=hlnstance; 

return(CreateMainWindow(hlnstance,hPrevInstance, 
IpszCmdParam,nCmdShow) ) ; 

} 

LRESULT FAR PASCAL SelectProc(HWND hwnd,unsigned int message, 
WPARAM wParam,LPARAM lParam) 

{ 

HPEN oldpen; 

HBRUSH oldbrush; 

RECT rect; 

LPDRAWITEMSTRUCT lpdraw; 

PAINTSTRUCT ps; 

HDC hdc; 

switch(message) { 

case WM_CREATE: 

return(FALSE); 
case WM_DRAWITEM: 

lpdraw=(LPDRAWITEMSTRUCT)lParam; 
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return(DrawBitmapButton(hwnd,message, 
wParam,lParam,lpdraw->CtlID)); 
case WM_SYSCOMMAND: 

switch (wParam) { 

case IDABOUT: 

DoMessage(hwnd,ABOUT_MESSAGE); 
break; 

} 

switch(wParam & OxfffO) { 
case SC__CLOSE: 

SendMessage(hwnd,WM_COMMAND, 

FILE_EXIT,OL); 
break; 

} 

break; 

case WM_SIZE: 

return(FALSE) ; 
case WM_DESTROY: 

SendMessage(hwnd, WM_COMMAND,FILE_CLOSE,OL); 
PostQuitMessage(0); 
return(FALSE); 
case WM_PAINT: 

hdc=BeginPaint(hwnd,&ps); 

TileWindow(hwnd,hdc,"BackgroundBrush"); 

GetClientRect (hwnd, Street) ; 

//draw the tool bar 
oldbrush= 

SelectObject(hdc,GetstockObject(BLACK_BRUSH)); 
oldpen= 

SelectObject(hdc,GetStockObject(MULL_PEN)); 
Rectangle(hdc,rect.left,rect.top, 

rect.right+1,rect.top+BUTTON_DEEP+l); 
SelectObject(hdc,oldpen); 

SelectObject(hdc,oldbrush); 

//draw the grey thing below the tool bar 
oldbrush= 

SelectObject(hdc,GetStockObject(LTGRAY_BRUSH)); 
oldpen= 

SelectObject(hdc,GetStockObject(NULL_PEN)); 
Rectangle(hdc,rect.left,rect.top+BUTTON_DEEP, 
rect.right,rect.top+BUTTON_DEEP+4); 

SelectObject(hdc,oldpen); 

SelectObject(hdc,oldbrush); 

//make it look three-dimensional 
oldpen= 

SelectObject(hdc,GetStockObject(WHITE_PEN)); 
MoveTo(hdc,rect.left,rect.top+BUTTON_DEEP); 

LineTo(hdc,rect.right,rect.top+BUTTON_DEEP); 

MoveTo(hdc,rect.left,rect.top+BUTTON_DEEP+3); 
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LineTo(hdc,rect.right,rect.top+BUTT0N_DEEP+3); 
SelectObject(hdc,oldpen); 

EndPaint(hwnd,&ps); 
return(FALSE); 
case WM_COMMAND: 

switch (wPar am) { 
case IDEXIT: 

SendMessage(hwnd,WM_CLOSE,0,OL); 
break; 
case IDOK: 

DoMessage(hwnd,OK_MESSAGE); 
break; 

case IDCANCEL: 

DoMessage(hwnd,CANCEL_MESSAGE); 
break; 

case IDHELP: 

DoMessage(hwnd,HELP_MESSAGE); 
break; 

} 

return(FALSE) ; 

} 

return(DefWindowProc(hwnd,message,wPar am,lParam)); 


WORD GetDisplayBits() 

{ 

HDC hdc; 

WORD i; 

hdc=GetDC(NULL); 

i=(WORD)(GetDeviceCaps(hdc,PLANES) * 
GetDeviceCaps(hdc,BITSPIXEL)); 
if(i > 8) i=24; 

ReleaseDC(NULL,hdc); 

return(i); 


void CentreWindow(HWND hwnd) 

{ 

RECT rect; 
unsigned int x,y; 

GetWindowRect(hwnd,&rect); 

x=(GetSystemMetrics(SM_CXSCREEN)-(rect.right-rect.left))/2; 
y=(GetSystemMetrics(SM_CYSCREEN)-(rect.bottom-rect.top))/2; 
SetWindowPos(hwnd,NULL,x,y,rect.right-rect.left, 
rect.bottom-rect.top,SWP_NOSIZE); 
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void DoMessage(HWND hwnd,LPSTR message) 

i ( 

MessageBox(hwnd,message,"Message",MB_OK ! MB_ICONINFORMATION); 

i } 


int CreateMainWindow(HANDLE hlnstance,HANDLE hPrevInstance, 

LPSTR IpszCmdParam,int nCmdShow) 

{ 

HWND hwnd; 

HMENU hMenu; 

HBITMAP hBitmap; 

MSG msg; 

WNDCLASS wndclass; 

if (!hPrevInstance) { 

wndclass.style = CS_HREDRAW ! CS_VREDRAW; 
wndclass.lpfnWndProc=SelectProc; 
wndclass.cbClsExtra=0; 
wndclass.cbWndExtra=0; 
wndclass.hlnstance=hlnstance; 

wndclass.hIcon=LoadIcon(hlnstance,szAppName); 
wndclass.hCursor=LoadCursor(NULL,IDC_ARROW); 
wndclass.hbrBackground=GetStockObject(LTGRAY_BRUSH); 
wndclass.lpszMenuName=NULL; 
wndclass.lpszClassName=szAppName; 

if(!RegisterClass(&wndclass)) { 

DoMessage(NULL, 

"Error registering the application class."); 
return(FALSE); 

} 

} 

hlnst=hlnstance; 

hwnd = CreateWindow(szAppName, 

APPLICATION, 

WS_OVERLAPPED ! WS_CAPTION ! WS_SYSMENU ! 

WS_MAXIMIZEBOX ! WS_MINIMIZEBOX ! 

WS_THICKFRAME, 

CW_U S EDEFAULT,CW_USEDEFAULT, 

CW_U S EDEFAULT,CW_USEDEFAULT, 

NULL, 

NULL, 

hlnstance, 

NULL); 

if(hwnd==NULL) { 

DoMessage(NULL,"Error creating the application window."); 
return(FALSE); 


W§ 
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CreateWindow("BUTTON", 


B S_PU SHBUTTON ! WS_CHILD ! WS_VISIBLE 
! WS_TABSTOP ! BS_OWNERDRAW, 

0 , 

0 , 

BUTTON_WIDE, 

BUTTON_DEEP, 
hwnd, 

(HMENU)IDOK, 
hlnst ; 

NULL); 


CreateWindow("BUTTON", 


BS_PUSHBUTTON ! WS_CHILD ! WS_VISIBLE 
! WS_TABSTOP ! BS_OWNERDRAW, 
BUTTON_WIDE, 

0 , 

BUTTON_WIDE, 

BUTTON_DEEP, 
hwnd, 

(HMENU)IDCANCEL, 
hlnst, 

NULL); 


CreateWindow("BUTTON", 


BS_PUSHBUTTON ! WS_CHILD ! WS_VISIBLE 
! WS_TABSTOP ! BS_OWNERDRAW, 
BUTTON_WIDE * 2, 

0 , 

BUTTON_WIDE, 

BUTTON_DEEP, 
hwnd, 

(HMENU)IDHELP, 
hlnst, 

NULL); 


CreateWindow("BUTTON", 


BS_PUSHBUTTON ! WS_CHILD ! WS_VISIBLE 
! WS_TABSTOP ! BS_OWNERDRAW, 
BUTTON_WIDE * 3, 

0 , 

BUTTON_WIDE, 

BUTTON_DEEP, 
hwnd, 

(HMENU) IDEXIT, 
hlnst, 

NULL); 
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Continued. 

if(LOBYTE(GetVersion()) >= 4) 

hBitmap=LoadBitmap(hlnst,"MenuBitmap95"); 

else 

hBitmap=LoadBitmap(hlnst,"MenuBitmap31"); 

hMenu=GetSystemMenu(hwnd,FALSE); 

AppendMenu(hMenu,MF_SEPARATOR,NULL,NULL); 

AppendMenu(hMenu,MF_BITMAP,IDABOUT,(LPSTR)(DWORD)hBitmap); 

CentreWindow(hwnd); 

ShowWindow(hwnd,nCmdShow); 

UpdateWindow(hwnd); 

while(GetMessage(&msg,NULL,0,0)) { 

TranslateMessage(&msg); 

DispatchMessage(&msg); 

} 

DeleteObject(hBitmap); 

UnregisterClass(szAppName,hlnst); 

return (msg.wParam) ; 

} 

#define DestroyAllObjects() {\ 

if(hOldBitmap != NULL) SelectObject(hMemoryDC,hOldBitmap);\ 
if(hMemoryDC !=NULL) DeleteDC(hMemoryDC);\ 

if(handle != NULL && lpbi != NULL) UnlockResource(handle);\ 
if(handle != NULL) FreeResource(handle);\ 
if(hBitmap != NULL) DeleteObject(hBitmap);\ 

} 

WORD TileWindow(HWND hwnd,HDC hdc,LPSTR bitmap) 

{ 

PALSTATE ps; 

LPBITMAPINFOHEADER lpbi=NULL; 

HANDLE handle=NULL; 

RECT rect; 

HBITMAP hBitmap=NULL,hOldBitmap=NULL; 

HDC hMemoryDC=NULL; 
short int far *ip; 
char palette[768]; 
int i,j,x,y; 

if((handle=LoadResource(hlnst, 

FindResource(hlnst,bitmap,RT_BITMAP)))==NULL) { 
DestroyAllObjects(); 
return(FALSE); 

} 


if((lpbi=(LPBITMAPINFOHEADER)LockResource(handle))==NULL) { 
DestroyAllObjects(); 





Continued. 

return(FALSE); 

} 

GetDibPalette((LPBITMAPINFO)lpbi,palette); 


SaveDC(hdc); 


if((hBitmap=CreateDIBitmap(hdc,lpbi,CBM_INIT, 

LPBimage(lpbi),(LPBITMAPINFO)lpbi,DIB_RGB_COLORS))==NULL) 
DestroyAllObjects(); 

return(FALSE); 


} 


if((hMemoryDC=CreateCompatibleDC(hdc)) == NULL) { 
DestroyAllObjects(); 
return(FALSE); 

} 


if((hOldBitmap=SelectObject(hMemoryDC,hBitmap))==NULL) { 
DestroyAllObjects(); 
return(FALSE); 

} 

RealizeWindowPalette(hdc,palette,LPBbits(lpbi),&ps); 


GetClientRect(hwnd,&rect); 


i=rect.right-rect.left; 

x=i/LPBwidth(lpbi); 

if(i % LPBwidth(lpbi)) ++x; 

j =rect.bottom-rect.top; 

y=j/LPBdepth(lpbi); 

if(j % LPBdepth(lpbi)) ++y; 

for(i=0;i<=y;++i) { 

for(j =0;j<=x;++j) { 

SetWindowOrg(hdc, 

-(j *LPBwidth(lpbi)), 

-(i*LPBdepth(lpbi))); 

BitBlt( 

hdc, 

0, 

0, 

LPBwidth(lpbi), 
LPBdepth(lpbi), 
hMemoryDC, 

0, 

0, 

SRCCOPY); 
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} 

; } 

UnrealizeWindowPalette(hdc,&ps); 

RestoreDC(hdc,-1); 

DestroyAllObjects(); 
return(TRUE); 

} 

#undef DestroyAllObjects() 
ttpragma argsused 

int DrawBitmapButton(HWND hwnd,WORD message, 

WORD wParam,LONG lParam,WORD id) 

I { 

LPDRAWITEMSTRUCT lpdraw; 

HBRUSH hbrush,oldbrush; 

HANDLE hBitmap; 

static WORD pattern[]={0x55,Oxaa,0x55,Oxaa,0x55,Oxaa,0x55,Oxaa}; 
int n; 

lpdraw=(LPDRAWITEMSTRUCT)1 Par am; 

if(lpdraw->itemState & ODS_SELECTED) n=id+3000; 
else if(lpdraw->itemState & ODS_FOCUS) n=id+5000; 
else n=id+1000; 

if((hBitmap=LoadResource(hlnst, 

FindResource(hlnst,MAKEINTRESOURCE(n), 

RT_BITMAP))) != NULL) { 

Drawlmage(lpdraw->hDC,lpdraw->rcItern.left, 
lpdraw->rcItern.top,hBitmap,SRCCOPY); 

FreeResource(hBitmap); 

i } 

if(lpdraw->itemState & ODSJDISABLED) { 

SaveDC(lpdraw->hDC); 

hBitmap=CreateBitmap(8,8,1,1,(LPSTR)pattern); 
hbrush=CreatePatternBrush(hBitmap); 
oldbrush=SelectObj ect(lpdraw->hDC,hbrush); 

n=SetROP2(lpdraw->hDC,R2_MERGEPEN); 

Rectangle(lpdraw->hDC,lpdraw->rcltem.left+1, 

lpdraw->rcItem.top+1,lpdraw->rcltem.right-1, 
lpdraw->rcltern.bottom-1); 

SetROP2(lpdraw->hDC,n); 


SelectObj ect(lpdraw->hDC,oldbrush); 
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Continued. 

DeleteObject(hbrush); 

DeleteObject(hBitmap); 

RestoreDC(lpdraw->hDC,-1); 

} 

return(FALSE); 

} 

void Drawlmage(HDC hdc,WORD x,WORD y,HBITMAP image,DWORD op) 

{ 

PALSTATE ps; 

HDC hMemoryDC; 

HBITMAP hBitmap,hO1dBitmap; 

LPBITMAPINFOHEADER lpbi; 
char palette[768]; 

if(image==NULL) return; 

if((lpbi=(LPBITMAPINFOHEADER)LockResource(image))==NULL) 
return; 

GetDibPalette((LPBITMAPINFO)lpbi,palette); 

RealizeWindowPalette(hdc,palette,LPBbits(lpbi), &ps); 

if((hBitmap=CreateDIBitmap(hdc,lpbi,CBM_INIT, 

LPBimage(lpbi),(LPBITMAPINFO)lpbi, 

DIB_RGB_COLORS)) !=NULL) { 
if((hMemoryDC=CreateCompatibleDC(hdc)) != NULL) { 

hOldBitmap=SelectObject(hMemoryDC,hBitmap); 
if(hOldBitmap) { 

BitBlt(hdc,x,y,LPBwidth(lpbi), 

LPBdepth(lpbi),hMemoryDC,0,0,op); 

SelectObject(hMemoryDC,hOldBitmap); 

} 

DeleteDC(hMemoryDC); 

} 

DeleteObject(hBitmap); 

} 

UnrealizeWindowPalette(hdc,&ps); 

UnlockResource(image); 

} 

The first call in TileWindow uses LoadResource to load the bitmap 
specified by the bitmap argument. In this case, the argument would 
be BackgroundBrush, the name of the resource. Note that you can 
use either LoadResource or LoadBitmap to load bitmaps for 
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display—the former will return a handle to a device-independent 
bitmap and the latter an HBITMAP handle; that is, a handle to a 
BITMAP object. A BITMAP doesn’t include a definition of its attendant 
palette—storing an image this way would entail that it either restrict 
itself to the colors in the Windows reserved palette or that it have a 
suitable palette stored with it. A device-dependent bitmap is more 
convenient—once it has been loaded, it’s converted to a device¬ 
dependent bitmap through the CreateDI Bitmap function. The 
HBITMAP returned by CreateDIBitmap is suitable for selecting into a 
device context and moving around with BitBIt. The BitBIt function is 
considerably quicker than SetDIBitsToDevice. In this case, it will get 
to take advantage of having to convert the source bitmap to the 
device-dependent format of its HDC only once, even though it will be 
painted several times. 

The TileWindow function uses RealizeWindowPalette from DIBLIB to 
realize the background bitmap’s palette. This isn’t actually necessary 
for the bitmap I’ve used here, as all its colors exist in the Windows 
reserved palette. The RealizeWindowPalette function uses a 
PALSTATE object to store several things it allocates—you must call 
UnrealizeWindowPalette to free up these things. 

Once its HDC is ready to rip, TileWindow repeatedly calls BitBIt to fill 
the destination window. The BitBIt function was discussed in chapter 1. 

The CreateMainWindow function of BMPTOYS does the obvious 
window creation tasks to get the main window of the application ready 
for action, but it also creates four child windows of the type BUTTON. 
These manage the tool bar in the main window, although they do so in 
a somewhat unusual way. They create conventional Windows 
buttons—that is, the objects they create will have the behavior of 
buttons—but they include the BS_OWNERDRAW flag. This means 
that, while Windows will respond to clicks on them as it would for 
conventional buttons, it won’t actually draw anything in their client 
areas. Rather, any time it would otherwise have redrawn the buttons, it 
will send a WM_DRAWITEM message to the message handler for the 
parent window of the buttons. In this case, the WM_DRAWITEM 
messages will appear at SelectProc, near the top of BMPTOYS.CPP. 
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When a WM_DRAWITEM message appears, its IParam argument is a 
far pointer to a DRAWITEMSTRUCT object. This will define where the 
object is to be drawn and what state it’s to be drawn in. The 
information it contains will vary with the nature of the object—in 
addition to owner draw buttons, for example, Windows allows for 
owner draw list boxes. In the latter case, a DRAWITEMSTRUCT will 
be used to define each visible item in a list box being drawn, allowing 
your application to decide what the item will look like. 

The SelectProc function calls DrawBitmapButton in response to a 
WM_DRAWITEM message. It’s declared near the bottom of 
BMPTOYS.CPP. 

It’s probably fair to say that my version of DrawBitmapButton is 
rather more fanciful than real-world concerns would make it. It has 
been written to allow for 256-color owner draw buttons, which look 
nice but would be both too slow and too awkward to use in a proper 
application. You would likely want to restrict your buttons to 16 colors 
drawn from the reserved Windows palette and use LoadBitmap rather 
than LoadResource to display the buttons. This would also eliminate 
the need for realizing the palette of each bitmap, which is fairly time- 
consuming. 


Organizing bitmapped buttons requires a bit of forethought. In 
BMPTOYS, the bitmaps are stored as three numbered resources for 
each button, and the arrangement corresponds to the way bitmaps are 
stored for the bitmap buttons used in Borland’s BWCC.DLL custom 
dialog control library. Here’s how they look in BMPTOYS.RC: 


1001 

BITMAP 

3001 

BITMAP 

5001 

BITMAP 

1002 

BITMAP 

3002 

BITMAP 

5002 

BITMAP 

1101 

BITMAP 

3101 

BITMAP 

5101 

BITMAP 

1998 

BITMAP 

3998 

BITMAP 

5998 

BITMAP 


"1001.BMP" 
"3001.BMP" 
"5001.BMP" 
"1002.BMP" 
"3002.BMP" 
"5002.BMP" 
"1101.BMP" 
"3101.BMP" 
"5101.BMP" 
"1998.BMP" 
"3998.BMP" 
"5998.BMP" 
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The three states of a bitmapped button . 


The three bitmaps for each button correspond to the button in its 
normal state, its depressed state, and its focused state. These are 
illustrated in Fig. 5-5. 

In addition to any redrawing required to maintain its appearance, an 
owner draw button will ask to be redrawn when you click on it, when 
you release the mouse click, and when the focus changes to it or away 
from it. In the resource numbering system shown here, if id is the 
button’s resource identification, the following will be the appropriate 
bitmap resources to load and draw: 

id + 1000—Normal 

id + 3000—Depressed 

id + 5000—Focused 

As can be seen in Fig. 5-5, a depressed bitmap looks like the normal 
bitmap except that it’s shaded differently and its image is moved a few 
pixels down and to the left. A focused bitmap is identical to a normal 
bitmap except that there’s a focus marquee around its title text. A 
depressed bitmap can be changed into a focused bitmap through an 
extended treatment plan of Prozac. 

If Ipdraw is a far pointer to a DRAWITEMSTRUCT defining the owner 
draw button to be drawn, DrawBitmapButton can determine which of 
the three bitmaps to load like this: 

int n; 

if(lpdraw->itemState & ODS_SELECTED) n=id+3000; 
else if(lpdraw->itemState & ODS_FOCUS) n=id+5000; 
else n=id+1000; 


The value of n will be the resource number of the bitmap to be loaded. 
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The version of DrawBitmapButton illustrated in BMPTOYS.CPP that 
calls Drawlmage to display its bitmap, which was touched on a 
moment ago, is considerable overkill for most normal applications. It 
can be seen at the very bottom of the source listing. Note that, while 
this is a fairly generic bitmap drawing function, it has been designed to 
work with device-independent bitmaps loaded by LoadResource. It 
can’t be passed a handle to a device-independent bitmap created by 
CreateDIB —resource handles and memory handles are not 
interchangeable under Windows. 

The rest of DrawBitmapButton takes care of the possibility of disabled 
owner draw buttons—which, incidentally, don’t turn up in BMPTOYS. 
If lpdraw->itemState indicates that a button is disabled, the 
DrawBitmapButton function will paint its bitmap and then paint over 
it with a pattern brush having every other pixel set. This will have the 
effect of making it look grayed. 

The final unusual bitmap in BMPTOYS is the lizard in its system 
menu. Note that, while I’ve created a custom bitmapped element in 
the system menu of this application, the same approach can be used 
for any menu item in any type of conventional Windows menu. Unlike 
the previous two lizards, this one requires almost no work on the part 
of the application that uses it. Windows does almost everything by 
itself. 

To add a bitmap as a menu item, you must load the bitmap from the 
resource list of your application with a call to LoadBitmap and 
append it to the menu in question. Here’s how this works in 
BMPTOYS: 

HBITMAP hBitmap; 

HMENU hMenu; 

hBitmap=LoadBitmap(hlnst,"MenuBitmap95"); 

hMenu=GetSystemMenu(hwnd,FALSE); 

AppendMenu(hMenu,MF_SEPARATOR,NULL,NULL); 

AppendMenu(hMenu / MF_BITMAP / IDABOUT,(LPSTR)(DWORD)hBitmap); 

If you wanted to add a bitmap menu item to a menu other than the 
System menu, you would use GetMenu rather than GetSystemMenu 






to fetch hMenu. The value IDABOUT is the resource ID of the About 
item—it’s defined in BMPTOYS.CPP. 

There are some considerations in choosing a bitmap to use within a 
Windows menu. A 16-color bitmap that uses colors from the Windows 
reserved palette will provide the most attractive results—bitmaps with 
more color depth will be remapped by Windows down to 16 colors if 
your application runs under Windows 3.1, and you might experience 
some unexpected color shifts if you use a 256-color bitmap in a menu 
under Windows 95. The BMPTOYS application actually includes two 
bitmaps for its about menu—it uses a 16-color version if it finds itself 
running under Windows 3.1. 
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NTIL quite recently, the Targa hardware and its attendant TGA 
files were somewhat exotic for most PC users. The Targa 
boards were an early high-end PC display system, offering true color 
displays at a time when getting decent monochrome graphics was 
considered an achievement in some circles. Of course, there was a 
drawback to the Targa boards. They cost more than some of the 
computers that drove them. 

In addition to engendering the Targa display hardware itself, the 
Truevision company that created them also saw the development of 
several applications suited to high-end color, including Lumina, a 
superbly functional true color painting application and photographic 
retouching package. 

For a long time, one pretty well needed a Targa board to be able to 
display anything like a passable representation of the images in Targa 
files. As such, Targa images rarely made it down into the lower orders 
of the food chain, and there was little need to deal with them. 

Many contemporary high-end PC display cards can display true color 
with most of the facilities of a Targa board—it’s unlikely that you’ll 
encounter Truevision’s hardware in real life. The Targa file format is 
still very much extant, however. 

There are several things that will make Targa files attractive if your 
applications will be dealing with high-end color. One of these is their 
relative obscurity until quite recently. Because few software packages 
outside the restricted cloister of Targa users have traditionally 
supported Targa files, there has been little opportunity for 
programmers to misread the Targa specification and litter the known 
universe with slightly illegal Targa images—as has been true of PCX 
and TIFF files, for example. In fact, the Targa specification is 
agreeably unambiguous and defines a format so simple as to make it 
all but impossible to mangle. 

This is, perhaps, a dangerous thing to suggest. One of the axioms of 
Murphy’s Law has it that nothing is foolproof because fools are so 
ingenious. 









Because the Targa hardware was initially one of the few paths 
available to actually do something with the output of color scanners, 
most scanner support software will export images in the Targa format. 
The Windows applications written to fine-tune scanned images—Aldus 
PhotoStyler, Corel PhotoPaint, and so on—have been among the 
foremost users of Targa images for this reason. 

Figure 6-1 illustrates one of the most commonly encountered Targa 
images loaded into Aldus PhotoStyler. The Targa Eagle is an example 
file provided by Truevision with its hardware. 
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Targa files represent one of the most powerful of all the high-end 
color image file formats to be discussed in this book, although the 
features that differentiate them from the other formats capable of 
supporting true color are ones that will find few applications under 
Windows. Despite their flexibility, Targa files are pretty easy to work 
with. Most of the tricky things that have been applied to palette color 
pictures under the formats discussed earlier in this book don’t really 
work when they find themselves confronted with a true color picture, 
and as such they don’t appear in the Targa specification. 

Targa files usually have the extension TGA. 

_±! Targa color 

One of the attractive aspects of Targa files as a medium for storing 
high-end true color images is that it offers a variety of options for 
doing so. You might want to compare this to the way PCX files handle 
24-bit images—they come in one flavor only, and it might not be one 
ideally suited to your applications. 

Thus far in this book I’ve discussed true color pictures as 24-bit 
images; that is, with three bytes of color information per pixel. This 
would not be an accurate way to describe them for Targa files. The 
Targa specification defines three storage formats for true color 
pictures, supporting 16, 24, and 32 bits per pixel. 

A 24-bit Targa file is probably the easiest to understand, as it’s similar 
to the 24-bit image formats that have turned up in conjunction with 
BMP and PCX files. Each pixel in such an image consists of three 
bytes, one each for the red, green, and blue component of the color it 
defines. The only difference between the Targa 24-bit line format and 
that of some of the other 24-bit formats dealt with in this book is that 
it stores its pixels in the order blue, green, red. 

This is fairly convenient under Windows actually as this is also how 
Windows likes to see its bitmaps. 
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Targa 32-bit pixels are actually just 24-bit pixels with an extra byte 
tacked on. The fourth byte defines transparency, or what people who 
are really tight with high-end color and like sophisticated-sounding 
words call alpha channels. This value tells a suitable application how 
to overlay one Targa image atop another. Each pixel can tell the 
software how much it is to blend with an underlying pixel. If the high- 
order bit of the fourth pixel is set, the low-order seven bits define the 
amount of transparency for that pixel. If it’s clear, the pixel is wholly 
opaque. 

Windows’ bitmap manipulation facilities do not include functions to 
implement transparency, and while you could write software to 
manipulate transparent images, it would be somewhat involved and 
fairly processor intensive. It’s arguably beyond the scope of this book, 
and we won’t be dealing with it in this chapter. The code to be 
discussed shortly will read 32-bit Targa files but will ignore their 
transparency bytes. 

The 16-bit Targa color format offers true color on a budget—or 
perhaps more accurately, on a diet. It defines each pixel with five bits 
each for the red, green, and blue color components, rather than eight. 
The resulting 15 bits can be stored in two bytes, rather than three, 
with one bit left over. The final bit is used as a transparency flag. This 
is similar to what was described in chapter 1 as high color. 

Figure 6-2 illustrates the relationship between 16- and 24-bit pixels. 

The reduced number of bits of color in a 16-bit Targa image doesn’t 
affect the brightness or the color of such an image. It does, however, 
reduce the precision to which color can be defined. A 24-bit image 
can draw its colors from a range of 16,777,216 possible shades. A 
16-bit file has only 32,768 possible colors to work with. This covers 
the same range as the colors for a 24-bit image, but with fewer 
gradations. 

In practice, 16-bit color still looks pretty respectable. To be sure, 
unless you have a Windows driver capable of displaying true color, you 
won’t be able to tell the difference. 







As has been touched on earlier in this book, scanned true color images 
don’t compress well, and in most cases, it’s better not to try to 
compress them at all, lest they retaliate by getting larger still. A 640- 
by-480 pixel, 24-bit image stored as a 24-bit Targa file would require 
a bit over 900 kilobytes of disk space to store. The same image stored 
as a 16-bit file would only require slightly over 600 kilobytes, albeit 
with a slight loss in color resolution. This isn’t quite the same as 
compression, in that it actually involves throwing away some of the 
color information, but it’s not a bad compromise. 











While they’re typically used to store true color images, it’s worth 
noting that Targa files can contain monochrome and 8-bit palette 
color and gray scale pictures as well. 

The Targa format can store pictures either uncompressed or with a 
simple form of run-length compression, which will be discussed later 
in this chapter. While its run-length compression is unlikely to be 
effective when it’s applied to scanned images, it can be useful for 
drawn graphics. 


Targa file structure 

There are a number of complex extensions defined for the Targa 
format that can provide it with some of the capabilities of the GIF 
extension blocks and of the TIFF format’s tags, the latter to be 
discussed later in this book. In practice, these features are virtually 
never used. They won’t be discussed in this chapter, and the code to 
be dealt with herein will ignore them if you do happen to encounter a 
Targa file that includes them. The remaining elements of a Targa file 
are exceedingly simple and should offer few complexities to 
applications that want to read and write images in the Targa format. 

A Targa file begins with a header that defines the image in the 
remainder of the file. Here’s what it looks like. 


typedef struct { 

char identsize; 
char colormaptype; 
char imagetype; 

unsigned short int colormapstart; 
unsigned short int colormaplength; 
char colormapbits; 
unsigned short int xstart; 
unsigned short int ystart; 
unsigned short int width,depth; 
char bits; 
char descriptor; 

} TGAHEAD; 


Because the Targa format was born on PC hardware, the multiple-byte 
numbers in the header are structured as Intel-style objects. 









It’s worth noting that the authentic Truevision Targa specification 
defines the structure of the start of a Targa file somewhat differently. 

In effect, it specifies a more complex header with several variable-size 
objects therein. Inasmuch as the C language does not get along at all 
well with the notion of variable-size structs, we’ll handle the fixed part 
of the header as it has been defined here and the variable-length fields 
that might follow it as data when we come to them. 

The identsize field of a TGAHEAD object defines the number of bytes 
that will occur after the header, to a maximum of 255. This extra field 
will contain a text description or identification for the image in the file, 
if one exists. Most Targa files don’t use this facility, and the identsize 
field will be set to zero. 

The colormaptype field defines whether the file being read has a color 
map; that is, a palette. Palettes are usually included only for 8-bit color 
images. However, some applications for Targa files might include a 
palette for a true color images, such that the image can be remapped 
to the palette if need be without the requirement of quantizing a 
palette for the purpose. 

If this field contains zero, there will be no palette information. If it 
contains one, a palette will follow the header. 

According to the Truevision specification, there are 256 possible types 
of color maps, of which the first 128 are reserved by Truevision for its 
own use and the latter 128 are available for proprietary third-party 
applications. As such, it’s uncertain what one should do with a Targa 
file having something other than zero or one in this field. 

The imagetype field contains a code that will define the type of image 
the file being read contains. The following are the images types 
currently defined by Truevision: 

1— Uncompressed palette-driven image. 

2— Uncompressed RGB image. 

3— Uncompressed monochrome image. 

9—Run-length encoded palette-driven image. 









>• 10—Run-length encoded RGB image. 

11—Run-length encoded monochrome image. 


The Targa specification notes that values of 0 through 127 should be 
considered legal proprietary codes for image storage that Truevision 
might dream up some time in the future. Values from 128 on up can 
be used for custom storage types. In fact, these six values are all 
you’re likely to encounter. As such, checking for the presence of one 
of these numbers in this field is a moderately safe way to make sure 
that your software actually has been given a Targa file to read. 

The colormapstart field defines which color value in a palette the first 
color in the file’s color map should represent. While this field will 
normally be zero, indicating that the first color defined by the file 
corresponds to the first color in the image, this need not always be so. 

The colormaplength field defines the number of colors in the color 
map. In a file having more than 8 bits of color—that is, a true color 
image—both the colormapstart and colormaplength values will 
usually be zero. 

The colormapbits field defines how the data in the color map for a 
Targa file will be structured. The color map entries are defined in the 
same way as the pixels in a Targa file; that is, as having 16, 24, or 32 
bits of color. As such, the colors in a palette-color Targa file could 
include transparency values. Note that this value defines the number 
of bits of color per palette entry, not the number of bits of color for 
the pixels in the image itself. In a true color file without a palette, this 
field would contain zero. 

Despite the flexibility of the color map options available under the 
Targa specification, Targa files are rarely used to hold palette-driven 
images. Their principal applications are for storing true color 
pictures—there are much better ways to deal with 256-color graphics. 

The xstart and ystart values specify the distance from the upper-left 
corner of your screen to the upper-left corner of the image. These 
values will both be zero in most cases—they’ll be ignored, and will be 








assumed to be zero, by the Targa reader to be discussed in this 
chapter. 

The width and depth values of a TGAHEAD object define the 
dimensions of the image being read. Note that these will only be 
equivalent to the number of bytes involved for 8-bit images. A 24-bit 
image would require width*3 bytes to hold one line. 

The bits field defines the number of bits of color information in Targa 
file. This can be 1, 8, 16, 24, or 32. In effect, this also defines how to 
interpret the structure of the pixels that will ultimately be read from 
the file. 

The descriptor field is a collection of flags that can be useful in 
interpreting a Targa image. The first four bits have to do with the 
transparency information in a Targa file and aren’t of much use to the 
code in this chapter. Bits four and five, however, can affect the way a 
Targa image is handled. They specify the image orientation. 

If descriptor & 0x20 is true, the first line read from the file should be 
considered the first line of the image; that is, the image is stored right 
way up. If it’s not true, the image is stored upside down. If descriptor 
& 0x10 is true, the image has been stored flipped right to left and will 
have to be flipped again if it’s to appear correctly. 

Figure 6-3 illustrates the effect of these two bits. 

As an aside, two of the most common problems encountered in 
writing software to read Targa files is in handling these two bits of the 
descriptor incorrectly and in forgetting that the red and blue values in 
a Targa pixel or color map entry are the reverse of what you would 
normally expect. These are things to watch for when you’re writing an 
application that uses Targa files. 

Following the fixed portion of a Targa file’s header, you will find the 
image identification string if the identsize value of the header was 
greater than zero. Beyond this will be the color map if it exists. The 
next byte in the file should be the first byte of the image data itself. 
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How the descriptor orientation bits affect the image storage in a Targa file. 

If the imagetype field of a Targa header indicates that the image is 
uncompressed, it can be read from the file with almost no 
manipulation. The three run-length encoded types will require a bit 
more code to deal with correctly. It’s worth noting that, in both cases, 
the result of unpacking a true color Targa file for use with the 
VIEWER application will be a 24-bit image. As such, the alpha 
channel information in a 32-bit file will be discarded, and 16-bit two- 
byte pixels will be expanded out to 24-bit, 3-byte pixels. While this 
latter format is somewhat wasteful of memory, keep in mind that 



Windows itself doesn’t have a device-independent bitmap format for 2- 
byte pixels. 

Targa run-length encoding—when it turns up at all—is agreeably 
uncomplicated. It might be argued that a function that is almost never 
used can get away without doing very much. 

Compressed Targa images will appear in Targa files with imagetype 
values of 9, 10, and 11. In this case, the first byte of a line is the first 
byte of a compressed field. It should be regarded as a key byte. The 
length of the field will be one more than the value held in the low- 
order 7 bits. If the high-order bit is set, the field is a run of pixels. If 
it’s not set, the field is a string. 

It’s important to keep in mind that, when you’re looking at Targa run- 
length compression, with the exception of monochrome TGA files, all 
the fields work in pixels, rather than in bytes. The number of bytes in 
a pixel varies with the number of bits of color in the file. As such, a 
compressed field with a length of 10 in a file with 24 bits of color 
would actually involve 30 bytes of uncompressed data—that’s 10 
pixels of 3 bytes each. 

Once one field of a line has been uncompressed, the next byte read 
from the file should be regarded as being the key byte of the next field. 
The process should be repeated until a whole line is unpacked. As with 
most other image file formats, compressed Targa lines are constrained 
to end on even line boundaries. 

Having read a Targa image line, you might have to reverse it right to 
left, depending on the status of the flags in the descriptor field of its 
header. 

It’s worth noting that the run-length compression method used by 
Targa files is fairly processor-intensive compared to, say, the run- 
length encoding used by 24-bit PCX files. You’ll probably find that all 
other things being equal, a run-length encoded TGA file will take 
longer to unpack. 

While the TGA reader code to be discussed in a moment will read all 
the variations on Targa files discussed in this chapter, the writer will 
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only write simple uncompressed files. The true color images it creates 
are stored with 24 bits per pixel, just as they are under Windows. If 
you have applications for other sorts of Targa files—those with 
compressed images or with different color depth for their true color 
pictures—you might want to modify the code presented here. 


The TGALIB library 

Of a level of complexity not vastly removed from the PCX and BMP 
libraries discussed earlier in this book, the TGALIB.CPP listing 
shouldn’t prove troubling unless you have a background in political 
science. It’s shown in Fig. 6-4. 


/* 


TGA Library 

Copyright (c) 1995 Alchemy Mindworks Inc. 


*/ 


#include <windows.h> 

#include <stdio.h> 

#include <string.h> 

#include <stdlib.h> 

#include "winbit.h" 

HANDLE hlnst; 

typedef struct { 

char identsize; 
char colourmaptype; 
char imagetype; 

unsigned short int colourmapstart; 
unsigned short int colourmaplength; 
char colourmapbits; 
unsigned short int xstart; 
unsigned short int ystart; 
unsigned short int width,depth; 
char bits; 
char descriptor; 

} TGAHEAD; 

typedef TGAHEAD FAR *LPTGAHEAD; 
short int expandbits[32] = { 

The TGALIB.CPP source code. 


Figure 6-4 
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WORD TGAReadLine(LPSTR p,int fh,LPTGAHEAD lptga); 
void TGAReverse(LPSTR p,LPTGAHEAD lptga); 

WORD error=NO_ERROR; 

#ifdef _WIN32_ 

#pragma argsused 

DLL_EXPORT (BOOL) DllEntryPoint(HINSTANCE hlnstance, 
DWORD wDataSeg,LPVOID lpCmdLine) 

{ 

hlnst=hlnstance; 
return(TRUE); 

} 

#else 

#pragma argsused 

DLL_EXPORT (int) LibMain(HANDLE hlnstance, 

WORD wDataSeg,WORD wHeapSize, LPSTR lpCmdLine) 

{ 

hlnst=hlnstance; 

if (wHeapSize > 0) UnlockData(0) ; 
return(TRUE); 

} 

#pragma argsused 

DLL_EXPORT (int) WEP(int nParameter) 

{ 

return (TRUE); 

} 

#endif 



DLL_EXPORT (LPSTR) GetFileExtension() 

{ 

return("TGA"); 

} 

DLL_EXPORT (WORD) GetLibraryVersion() 

{ 

return ( (VERSION « 8) ! SUBVERSION); 

} 

#define DestroyAllObjects(err,success) {\ 

if(fh != -1) _lclose(fh);\ 

if(!success && handle != NULL) GlobalFree(handle);\ 
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error=err;\ 

} 

DLL_EXPORT (HANDLE) GetFilelnformation(LPSTR path) 

{ 

HANDLE handle=NULL; 
char palette[768]; 

TGAHEAD tga; 

unsigned int width,depth,bits; 
int i,n,fh; 

if((fh=_lopen(path,OF_READ))==-l) { 

DestroyAllObjects(BAD_OPEN,FALSE); 
return(NULL); 

} | 

if(_lread(fh,(LPSTR)&tga,sizeof(TGAHEAD)) ! = 

sizeof(TGAHEAD)) { 

DestroyAllObjects(BAD_READ,FALSE); 
return(NULL); 

} 

GetMonoPalette(palette); 

if(tga.imagetype!=0x01 && 
tga.imagetype!=0x02 && 
tga.imagetype!=0x03 && 
tga.imagetype!=0x09 && 
tga.imagetype!=0x0a && 
tga.imagetype!=0x0b) { 

DestroyAllObjects(BAD_FILE,FALSE); 
return(NULL); 

} 


width=tga.width; 
depth=tga.depth; 

if(tga.bits > 8) bits=24; 
else bits=tga.bits; 

_llseek(fh,(long)tga.identsize,SEEK_CUR); 

resetbuffer(); 

if(tga.colourmaptype) { 

switch(tga.colourmapbits) { 
case 32: 

for(i=tga.colourmapstart; 

i<tga.colourmaplength;++i) { 

if(i >= 768) break; 
palette[i*RGB_SIZE+RGB_BLUE]= 
getbufferedbyte(fh); 
palette[i*RGB_SIZE+RGB_GREEN]= 
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getbufferedbyte(fh); 
palette[i*RGB_SIZE+RGB_RED]= 
getbufferedbyte(fh); 
getbufferedbyte(fh); 

} 

break; 
case 24: 

for(i=tga.colourmapstart; 

ictga.colourmaplength;++i) { 
if(i >= 768) break; 
palette[i*RGB_SIZE+RGB_BLUE]= 
getbufferedbyte(fh); 
palette[i*RGB_SIZE+RGB_GREEN]= 
getbufferedbyte(fh); 
palette[i*RGB_SIZE+RGB_RED]= 
getbufferedbyte(fh); 

} 

break; 
case 15: 
case 16: 

for(i=tga.colourmapstart; 

i<tga.colourmaplength;++i) { 
if(i >= 768) break; 
n=getbufferedword(fh); 
palette[i*RGB_SIZE+RGB_RED]= 

expandbits[((n » 10) & Oxlf)]; 
palette[i*RGB_SIZE+RGB_GREEN]= 

expandbits[((n » 5) & Oxlf)]; 
palette[i*RGB_SIZE+RGB_BLUE]= 
expandbits[(n & Oxlf)]; 


} 

break; 

} 

if(bits==l) GetMonoPalette(palette); 

} 

else { 

if(bits==8) { 

for(i=0;i<256;++i) 

memset(palette+i*RGB_SIZE,i,RGB_SIZE); 

} 

} 

if((handle=CreateDibHeader(width,depth, 
palette,bits))==NULL) { 

DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

} 



DestroyAllObjects(NO_ERROR,TRUE); 







Continued. Figure 6-4 

return(handle); 

} 

#undef DestroyAllObjects() 

#define PutLine(p,n) hmemcpy(LPBimage(lpbi)+\ 

(DWORD)LPBlinewidth(lpbi)*(DWORD)(LPBdepth(lpbi)-(n)-1),\ 

(p),(DWORD)LPBIinewidth(lpbi)) 

#define DestroyAllObjects(err,success) {\ 

if(fh != -1) _lclose(fh);\ 
if(lpbi != NULL) GlobalUnlock(handle);\ 
if(linebuffer ! = NULL) FixedGlobalFree(linebuffer);\ 
if ({success ScSc handle != NULL) GlobalFree (handle) ; \ 
error=err;\ 

} ! 

DLL_EXPORT (HANDLE) ReadGraphicFile(LPSTR path) 

{ 

TGAHEAD tga; 

HANDLE handle=NULL; 

LPBITMAPINFOHEADER lpbi=NULL; 

LPSTR 1inebu f f er=NULL; 
char palette[768]; 
int incline,startline,endline; 
unsigned int width,depth,bits; 
int i,n,fh; 

if((fh=_lopen(path,OF_READ))==-l) { 

DestroyAllObjects(BAD_OPEN,FALSE); 
return(NULL); 

> ; 

if(_lread(fh,(LPSTR)&tga,sizeof(TGAHEAD)) != 

sizeof(TGAHEAD)) { 

DestroyAllObjects(BAD_READ,FALSE); 
return(NULL); 

} j 

GetMonoPalette(palette); 

if(tga.imagetype!=0x01 && 
tga.imagetype!=0x02 && 
tga.imagetype!=0x03 && 
tga.imagetype!=0x09 && 
tga.imagetype!=0x0a && 
tga.imagetype!=0x0b) { 

DestroyAllObjects(BAD_FILE,FALSE); 
return(NULL); 


width=tga.width; 
depth=tga.depth; 
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if(tga.bits > 8) bits=24; 
else bits=tga.bits; 

_llseek(fh,(long)tga.identsize,SEEK_CUR); 

if(tga.colourmaptype) { 

switch(tga.colourmapbits) { 
case 32: 

for(i=tga.colourmapstart; 

i<tga.colourmaplength;++i) { 
if(i >= 768) break; 
palette[i*RGB_SIZE+RGB_BLUE]= 
getbyte(fh); 

palette[i*RGB_SIZE+RGB_GREEN]= 
getbyte(fh); 

palette[i*RGB_SIZE+RGB_RED]= 
getbyte(fh); 
getbyte(fh); 

; } 

break; 
case 24: 

for(i=tga.colourmapstart; 

i<tga. colouinnaplength;++i) { 
if(i >= 768) break; 
palette[i*RGB_SIZE+RGB_BLUE]= 
getbyte(fh); 

palette[i*RGB_SIZE+RGB_GREEN]= 
getbyte(fh); 

palette[i*RGB_SIZE+RGB_RED]= 
getbyte(fh); 

} 

break; 
case 15: 
case 16: 

for(i=tga.colourmapstart; 

i<tga. colouirmaplength;++i) { 

if(i >= 768) break; 
n=getword(fh); 

palette[i*RGB„SIZE+RGB_RED]= 

expandbits[((n » 10) & Oxlf)] 
palette[i*RGB_SIZE+RGB_GREEN]= 

expandbits[((n >> 5) & Oxlf)]; 
palette[i*RGB_SIZE+RGB_BLUE]= 
expandbits[(n & Oxlf)]; 



} 

break; 

} 

if(bits==l) GetMonoPalette(palette); 

} 

else { 





} 


if(bits==8) { 

for(i=0;i<256;++i) 

memset(palette+i*RGB_SIZE,i,RGB_SIZE); 

} 


if((handle=CreateDib(width,depth,palette,bits))==NULL) { 
DestroyAllObj ects(BAD_ALLOC,FALSE) ; 
return(NULL); 

} 

if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(handle)) ==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

} 

if((linebuffer= 

FixedGlobalAlloc(LPBlinewidth(lpbi)+1024))==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

} 


resetbuffer(); 

if(!(tga.descriptor & 0x20)) { 

startline=depth-l; 
endline=-l; 
incline=-l; 

} 

else { 

startline=0; 
endline=depth; 
incline=l; 


for(i=startline;i != endline;i+=incline) { 
if(!TGAReadLine(linebuffer,fh,&tga)) { 
DestroyAllObjects(BAD_READ,FALSE); 
return(NULL); 

} 

TGAReverse(linebuffer,&tga); 

PutLine(linebuffer,i); 


DestroyAllObjects(NO_ERROR,TRUE); 
return(handle); 


} 

#undef DestroyAllObjects() 
#undef PutLine() 
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#define GetLine(p / n) hmemcpy((p),LPBimage(lpbi)+\ 

(DWORD)LPBlinewidth(lpbi)*(DWORD)(LPBdepth(lpbi)-(n)-1),\ 
(DWORD)LPBlinewidth(lpbi)) 

#define DestroyAllObjects(err,success) (\ 

if(fh != -1) _lclose(fh);\ 

if(fh != -1 && !success) DeleteFile(path);\ 
if(lpbi != NULL) GlobalUnlock(handle);\ 
if(linebuffer != NULL) FixedGlobalFree(linebuffer);\ 
if(extrabuffer ! = NULL) FixedGlobalFree(extrabuffer);\ 
error=err;\ 
j > 

DLL_EXPORT (WORD) WriteGraphicFile(LPSTR path, HANDLE handle) 

i { 

TGAHEAD tga; 

LPSTR linebuffer=NULL,extrabuffer=NULL; 

LPBITMAPINFOHEADER lpbi=NULL; 
char palette[768]; 
unsigned int width,depth,bits; 
unsigned int i,j,bytes,linewidth; 
int fh=-1; 

if((fh=_lcreat(path,0))==-l) { 

DestroyAllObjects(BAD_CREATE,FALSE); 
return(FALSE); 

} 

if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(handle))==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(FALSE); 

} 

width=LPBwidth(lpbi); 
depth=LPBdepth(lpbi); 
bits=LPBbits(lpbi); 

GetDibPalette((LPBITMAPINFO)lpbi,palette); 

linewidth=LPBlinewidth(lpbi); 

if((fh=_lcreat(path,0))==-l) { 

DestroyAllObjects(BAD_CREATE,FALSE); 
return(FALSE); 

} 

if ( (linebuffer= 

(LPSTR)FixedGlobalAlloc(linewidth+1024)) == NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(FALSE); 



if((extrabuffer= 
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(LPSTR)FixedGlobalAlloc(linewidth+1024)) == NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(FALSE); 

} 

if(bits==l) bytes=PIXELS2BYTES(width); 
else if(bits >1 && bits <=8) bytes=width; 
else bytes=width * RGB_SIZE; 

Imemset((LPSTR)&tga,0,sizeof(TGAHEAD)); 

if(bits==l) { 

tga.imagetype=0x03; 

tga.width=width; 

tga.depth=depth; 

tga.bits=l; 

tga.descriptor=0x20; 

} 

else if(bits > 1 && bits <=8) { 
tga.colourmaptype=0x01; 
tga.imagetype=0x01; 
tga.colourmaplength=2 5 6; 
tga.colourmapbits=24; 
tga.width=width; 
tga.depth=depth; 
tga.bits=8; 
tga.descriptor=0x20; 

} 

else { 

tga.imagetype=0x02; 

tga.width=width; 

tga.depth=depth; 

tga.bits=24; 

tga.descriptor=0x20; 

} 

if(_lwrite(fh,(LPSTR)&tga,sizeof(TGAHEAD)) != 

sizeof(TGAHEAD)) { 

DestroyAllObjects(BAD_WRITE,FALSE); 
return(FALSE); 

} 

/* write the palette */ 
if(tga.bits == 8) { 

resetbuffer(); 
for(i=0;i<256;++i) { 

putbufferedbyte(palette[i*RGB_SIZE+RGB_BLUE],fh); 
putbufferedbyte(palette[i*RGB_SIZE+RGB_GREEN],fh); 
putbufferedbyte(palette[i*RGB_SIZE+RGB_RED],fh); 

} 

putbufferedbyte(EOF,fh); 
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} 


for(i=0;i<depth;++i) { 

GetLine(linebuffer,i); 

if(bits==l) { 

if(_lwrite(fh,linebuffer,bytes) != bytes) { 
DestroyAllObjects(BAD_WRITE / FALSE); 
return(FALSE); 

} 

} 

else if(bits > 1 && bits <=4) { 

for(j=0;j<width;++j) 

extrabuffer[j++]=GetChunkyPixel(linebuffer,j); 

if(_lwrite(fh,extrabuffer,bytes) != bytes) { 
DestroyAllObjects(BAD_WRITE,FALSE); 
return(FALSE); 

} 

} 

else if(bits > 4 && bits <= 8) { 

if(_lwrite(fh,linebuffer,bytes) != bytes) { 
DestroyAllObjects(BAD_WRITE,FALSE); 
return(FALSE); 

} 

} 

else if(bits == 24) { 

if(_lwrite(fh,linebuffer,bytes) != bytes) { 
DestroyAllObjects(BAD_WRITE,FALSE); 
return(FALSE); 

} 

} 

} 


DestroyAllObjects(NO_ERROR,TRUE); 
return(TRUE); 

} 

#undef DestroyAllObjects() 

#undef GetLine() 


DLL_EXPORT (WORD) GetError(LPSTR text) 

{ 

if(text != NULL) lstrcpy(text,GetErrorText(error)); 
return(error); 

} 

DLL_EXPORT (LPSTR) GetCopyright() 

{ 

return("Copyright \251 1995 Alchemy Mindworks Inc."); 

} 
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DLL_EXPORT (LPSTR) GetNotice() 

{ 

return( 

"TGA or Targa is the format native to Truevision's\n" 
"Targa display hardware. It supports up to 32 bits of\n 
"colour, which is 24 bits plus eight bits of alpha\n" 
"channels." 



WORD TGAReadLine(LPSTR p,int fh ,LPTGAHEAD lptga) 

{ 

int c,i,n=0,size; 
int r,g,b,linesize; 

if(lptga->bits==l) linesize=PIXELS2BYTES(lptga->width); 
else linesize=lptga->width; 

if(lptga->imagetype==0x01 !! 

Iptga->imagetype==0x02 ! ! 

Iptga->imagetype==0x03) { 

switch(lptga->bits) { 
case 1: 

if(_lread(fh,p,PIXELS2BYTES(lptga->width)) != 

PIXELS2BYTES(lptga->width)) 
return(FALSE); 
break; 
case 8: 

if(_lread(fh,p,lptga->width) != lptga->width) 
return(FALSE); 
break; 
case 15: 
case 16: 

for(i=0;i<lptga->width;++i) { 

c=getbufferedword(fh); 

r=expandbits[((c » 10) & Oxlf)]; 
g=expandbits[((c » 5) & Oxlf)]; 
b=expandbits[(c & Oxlf)]; 

*p++=b; 

*p++=g; 

*p++=r; 

} 

break; 
case 24: 

for(i=0;i<lptga->width;++i) { 
b=getbufferedbyte(fh); 
g=getbufferedbyte(fh); 
r=getbufferedbyte(fh); 

if(r==EOF !! g==EOF !! b==EOF) 
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return(FALSE); 

*p++=b; 

*p++=g; 

*p++=r; 

} 

break; 
case 32: 

for(i=0;i<lptga->width;++i) { 

b=getbufferedbyte(fh); 
g=getbufferedbyte(fh); 
r=getbufferedbyte(fh); 
getbufferedbyte(fh); 
if(r==EOF ! ! g==EOF !! b==EOF) 
return(FALSE); 

*p++=b; 

*p++=g; 

*p++=r; 

} 

break; 

} 

} 

else { 

do { 

if((c=getbufferedbyte(fh)) == EOF) return(FALSE); 

size=(c & 0x7f)+1; 

n+=size; 

if(c & 0x80) { 

switch(lptga->bits) { 
case 1: 
case 8: 

if((c=getbufferedbyte(fh)) == EOF) 
return(FALSE); 
for(i=0;i<size;++i) *p++=c; 
break; 
case 15: 
case 16: 

if((c=getbufferedword(fh)) == EOF) 
return(FALSE); 


r=expandbits[((c >> 10) & Oxlf)]; 
g=expandbits[((c >> 5) & Oxlf)]; 
b=expandbits[(c & Oxlf)]; 

for(i=0;i<size;++i) { 

*p++=b; 

*p++=g; 

*p++=r; 

} 

break; 
case 24: 

b^getbufferedbyte(fh); 
g=getbufferedbyte(fh); 
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r=getbufferedbyte(fh); 
if(r==EOF ! ! g==EOF !! b==EOF) 
return(FALSE); 
for(i=0;i<size;++i) { 

*p++=b; 

*p++=g; 

*p++=r; 

} 

break; 
case 32: 

b=getbufferedbyte(fh); 
g=getbufferedbyte(fh); 
r=getbufferedbyte(fh); 
getbufferedbyte(fh); 
if(r==EOF ! ! g==EOF !! b==EOF) 
return(FALSE); 
for(i=0;i<size;++i) { 

*p++=b; 

*p ++ -g; 

*p++=r; 

} 

break; 

} 

} 

else { 

switch(lptga->bits) { 
case 1: 
case 8: 

for(i=0;i<size;++i) 

*p++=getbufferedbyte(fh); 
break; 
case 15: 
case 16: 

for(i=0;i<size;++i) { 

if((c=getbufferedword(fh)) == EOF) 
return(FALSE); 

r=expandbits[((c >> 10) & Oxlf)]; 
g=expandbits[((c >> 5) & Oxlf)]; 
b=expandbits[(c & Oxlf)]; 


*p++=b; 

*p++=g; 

*p++=r; 

} 

break; 

24: 

for(i=0;i<size;++i) { 

b=getbufferedbyte(fh); 
g=getbufferedbyte(fh); 
r=getbufferedbyte(fh); 
if (r==EOF ! ! g==EOF !! b==EOF) 
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return(FALSE); 


*p++=b; 

*p++=g; 

*p++=r; 

} 

break; 
case 32: 

for(i=0;i<size;++i) { 

b=getbufferedbyte(fh); 
g=getbufferedbyte(fh); 
r=getbufferedbyte(fh); 
getbufferedbyte(fh); 
if(r==EOF !! g==EOF !! b==EOF) 
return(FALSE); 


} 

} 

} while(n < 

} 

return(TRUE); 


*P++-b; 

*P ++ -g; 
*p++=r; 

} 

break; 


linesize); 


} 

void TGAReverse(LPSTR p,LPTGAHEAD lptga) 

{ 


LPSTR pr; 
int i; 


if(!(lptga->descriptor & 0x10)) return; 

if((pr=(LPSTR)FixedGlobalAlloc((long)lptga->width)) != NULL) { 

for(i=0;i<lptga->width;++i) pr[i]=p[lptga->width-l-i]; 
lmemcpy(p,pr,lptga->width); 

FixedGlobalFree(pr); 

} 

} 



The ReadGraphicFile in TGALIB deals with all the permutations of 
Targa files, and as such is modestly complex. Nothing it gets involved 
with is all that hard to understand, however. Note that it uses the 
buffer file-handling functions from WINBIT, requiring a call to 
ResetBuffer before things start happening. 





Having opened its source file, ReadGraphicFile fetches the first 
portion of the file into a TGAHEAD object and checks to see if the 
image type is one of the legal types it knows how to deal with. It also 
works out the image dimensions and the color depth and seeks along 
to where the palette information is stored, if any exists. 

A Targa file can store its palette color entries in any of the three color 
pixel formats that Targa files support for true color images. While 
most Targa palettes use conventional 3-byte RGB colors, the 
specification allows for 2- and 4-byte entries as well. The palette 
reader in ReadGraphicFile takes care of all these possibilities. 

Note that, in reading 15-bit palette entries, the palette reader makes 
use of the expandbits array defined at the top of TGALIB.CPP. This 
might require some explanation, as it seems as if there should be a 
simpler way to expand 16-bit colors to 24 bits. 

As was dealt with earlier in this chapter, a 16-bit color is a word with 
the first color index in the first 5 bits, the second color index in the 
second 5 bits, and the third color index in the third 5 bits. As such, if 
n is a word containing a 16-bit color, you could isolate the first color 
index by masking it: 

blue = n & 0x001f; 


The value 0x00If is what results when the first 5 bits of a number are 
set. 

A sixteen-bit color index of 0x00If corresponds to a 24-bit color index 
of 255—or at least, it should. It seems as if you should be able to 
simply shift this value left by 3 bits to arrive at the correct color index 
of OxOOff. If you try it, however, you’ll find that the result will be 
0x00f8—the three low-order bits in the resulting number will be left as 
zero. 

As there are only 32 possible values for a 5-bit number, the easiest 
way to get the correct values in expanding a 15-bit color to 24 bits is 
to store the right answers in a table and use the source indices to 
index it. Aside from creating the correct 24-bit color values, this is 
also exceedingly fast. 






Once the Targa palette has been read, the ReadGraphicFile function 
can work out which direction to read the file in and get to work 
unpacking lines. The TGAReadLine function will fetch the next line 
from the file, unpacking it and juggling its pixel structure as needs be, 
and TGAReverse will reverse it right to left if the TGAHEAD header 
for the file says this is necessary. The PutLine call is actually a macro 
defined before the declaration for ReadGraphicFile —it copies the 
contents of linebuffer to the image of the device-independent bitmap 
being assembled. 

The TGAReadLine function is fairly immense because it has to deal 
with the six different line structures possible in a Targa file at each of 
the five possible bit depths a Targa file can support. Despite this, 
there’s little in it that’s particularly complex. The three uncompressed 
types—image types one, two, and three—area just read a line at a 
time and swabbed a bit in the case of 16- and 32-bit lines. The three 
compressed types require that the file be read a byte at a time and run 
through the Targa run-length decompression algorithm. Once again, 
16- and 32-bit lines require some data adjustment. 

The TGAReverse function is called for all Targa files, but it does 
nothing if it’s confronted with a file that doesn’t need reversing. Lines 
that do need to be swabbed are copied into a new buffer in the reverse 
order and then copied back to the source line. 

The WriteGraphicFile function is quite a bit simpler than 
ReadGraphicFile, as it can safely ignore many of the Targa file 
options. It begins by creating the destination file and filling in the fields 
of a TG AHEAD object. It writes a palette for files that require one 
using 24-bit color entries. Finally, it writes the image data. This 
version of WriteGraphicFile doesn’t do run-length compression, and 
as each of the line structures in a Windows device-independent bitmap 
corresponds to a legal line structure in a Targa file—except for that of 
4-bit lines—it can usually just write the line data as it exists in the 
source bitmap. Bitmaps with 16 colors require that each pixel be 
expanded to a byte and the lines written as if they belonged to a 256- 
color bitmap—Targa files do not support 16 colors directly. It’s also 
important to note that a Windows device-independent bitmap will have 
its lines padded out to the next even word boundary. Targa files don’t 
do this. 






^1 Using Targa files 

There are a number of specific applications for Targa files, even if you 
never get within hailing distance of a real Targa board. You’ll probably 
find that they make a good medium for exporting files from a color 
scanner. They’ve also become the de facto 24-bit export bitmapped 
image format for many ray-tracing packages, inarguably one of my 
favorite unproductive applications for high-end computer hardware. 
Figure 6-5 illustrates a typical ray-traced Targa file. 



Ray tracing stored in a Targa file. Reality could never be this real. 


It’s also worth noting that Targa files and software to work with them 
do turn up on other platforms, most notably Macintosh systems. While 
the TIFF format is more readily accepted as a universal 24-bit image 
file format, the discussion of TIFF files later in this book might put you 
off the idea of using them, perhaps with good reason. 


Figure 6-5 
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The simple nature of the Targa format makes it a reliable way to deal 
with high-end color. It doesn’t really do very much, but it does it very 
well. 

You can obtain the complete Targa specification by contacting 
Truevision Inc., 7340 Shadeland Station, Indianapolis, Indiana, 
46256-3925. 
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HE TIFF format is the single most contrary, poorly defined, 
obstreperous, frustrating, bad tempered, overbearing, 
unfathomable, intractable, amorphous, nasty, venomous, toad¬ 
swallowing, poodle-stabbing, three-eyed, scabious, mutated 
extraterrestrial goat’s bridle of a graphics standard presently in use 
among PC applications. While this should not be construed as a 
suggestion that it might present you with untoward difficulties in 
applying it, you might find that you need a few passes through 
selected portions of this chapter to truly appreciate the magnitude of 
its general perversity. 

It’s worth noting that this chapter will not attempt to deal with all the 
subtleties and nuances of the TIFF specification—a book the size of 
this one could be devoted solely to the task. While the TIFF library to 
be dealt with herein will read pretty well any legal TIFF file it 
encounters, much of the actual code that does the work is mysterious 
and will remain that way. This is the first of three chapters that will 
use third-party libraries to deal with some of the tricky aspects of 
complex formats. TIFF is the most complex of the lot—think of trying 
to nail virtual mercury to the side of an enraged rhinoceros that isn’t 
really there and you’ll have a workable analogy for a TIFF file. 

The TIFF format was devised by a committee largely at the behest of 
Microsoft and Aldus. Its initial purpose was to provide an image file 
format that would be platform-independent, application-independent, 
and image-independent. A TIFF file should be able to store any image, 
be useful on any computer, be readable by all applications, and be 
applicable to virtually any task. Depending on how you want to look at 
the TIFF format, almost all or absolutely none of the foregoing is true. 
It’s possible to write a legal TIFF file that will do pretty well all of this. 
It’s equally possible to write a TIFF file that will do none of it. 

The acronym TIFF stands for “tag image file format.” 

The great thing about the TIFF specification is that it’s almost 
limitlessly flexible. It can be adapted to suit virtually any purpose. The 
drawback to it is that it’s so flexible as to make the prospect of writing 
a TIFF reader that will read all possible TIFF files exceedingly 
daunting. In addition, the TIFF specification is somewhat ambiguous in 







many areas. Were one to attempt such a task, the details of the task 
itself would probably be open to considerable interpretation. 

As has been touched on in previous chapters, one of the things that 
frequently makes reading image files from multiple sources uncertain 
is an initially ambiguous specification that is subsequently interpreted 
in different ways by different software authors. In most cases, such as 
that of the PCX specification, there are relatively few contentious 
areas of the format design. The TIFF specification has dozens of 
them. 

Figure 7-1 illustrates two TIFF files. The monochrome image is an 
exceedingly venerable scan from on old woodcut. The gray scale 
image has come from a contemporary ScanJet Plus scanner. 

Despite the overwhelming complexity of TIFF files, you’ll find the TIFF 
library to be discussed herein exceedingly simple because all the work 
is done by something called LIBTIFF, written by Sam Leffler. A 
monumental work, LIBTIFF will correctly sort out all the really weird 
bits of TIFF files and allows software like the TIFF library herein to 
deal with TIFF in moderately simple ways. As of this writing, LIBTIFF 
is available at no cost—the source code for it is included on the 
companion CD-ROM for this book. I’ll say a lot more about it later in 
this chapter. 


TIFF file structure 

One of the arguable limitations of simple image file formats, such as 
PCX, is that they offer very little room for expansion, and what there 
is tends to be a bit inflexible. It’s a good aphorism of software design 
that the unexpected wouldn’t be so named if it wasn’t hard to predict. 
Leaving “room for growth” in a format assumes that it will grow in a 
predictable way. 

In the case of the PCX format, when it came time to add 256-color 
capability to it, the authors of the format clearly found that they 
hadn’t left enough room for growth. 










Several TIFF files. Notice the absence of poodle-stabbing extraterrestrials- 
they’re present, but in keeping with the TIFF format, they re hiding. 


Figure 7-1 








Figure 7-1 



Continued. 


The TIFF specification defines image files as building blocks, such that 
each block defines a characteristic of the image being stored. Each 
block is called a “tag”—hence the format name—and each image is 
defined by a “directory,” or list of tags. A TIFF file can contain 
multiple directories and, hence, multiple images per file. The library in 
this chapter will deal with only one image per file, but you’re free to 
modify it if you like. 












The GIF specification implements something along these lines with its 
extension blocks, although the scope of the TIFF format’s tags is 
considerably broader. 

A typical TIFF file would consist of tags to define the dimensions of 
the image in question, tags to define how it’s stored and compressed, 
a tag to define its palette if it has one—and any number of other tags. 
There are optional TIFF tags to specify the name of the software that 
created the image in question, tags to improve the performance of the 
function that will decompress the image data in a file, tags to enhance 
the printing of an image on specific output devices, and so on. In fact, 
there are dozens of tags available to a TIFF writer, and applications 
are free to add proprietary TIFF tags to a TIFF file for their own use. 

By definition, any TIFF tag that your TIFF reader doesn’t understand 
or doesn’t care about can be skipped, so a TIFF file with dozens of 
optional tags will not require software to correctly interpret every one. 
Flowever, this doesn’t necessarily mean that some of those optional 
tags might not contain something useful—or perhaps even essential. 

A single TIFF tag defines one quantity or object that is pertinent to the 
file it’s describing. Hence there are TIFF tags called ImageWidth and 
ImageLength to specify the width and depth of an image. These tags 
contain integer values. There’s a tag called Software, which specifies a 
long integer representing the offset in a TIFF file where an ASCII 
string defining the name of the application that created the file resides. 
There’s a tag called ColorMap, which defines a long integer specifying 
the offset of a TIFF color map; that is, its palette data. 

There’s a partial list of TIFF tags along with a description of what 
they’re up to later in this chapter. 

Every TIFF tag consists of 12 bytes, of which the first two are a short 
integer that defines which tag is being defined. As such, if a TIFF reader, 
in reading through a directory of tags, locates a tag it doesn’t recognize 
or care about, it can just seek forward by 10 more bytes and read the 
next tag. 

If you’ve peeked at the tag definition list later in this chapter, you’ll 
know that the list of potential tag types is a bit enormous. The 
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structure of tags, however, means that you needn’t be too concerned 
about its enormity. 

A TIFF file begins with a small, predictable header. For the moment, it 
can be defined like this: 

typedef struct { 

unsigned short int numbertype; 
unsigned short int version; 
unsigned long offset; 

} TIFHEAD; 

In fact, for reasons that will become apparent in a moment, it can’t 
really just be read into a data structure and dealt with as you would 
other C language data. 

The numbertype element in a TIFF header will always contain one of 
two values: either 4949H or 4D4DH. It might make it easier if you 
note that 49H is the ASCII code for the letter I and 4DH is the ASCII 
code for the letter M. These stand for Intel and Motorola respectively. 
If the first word in a TIFF file contains the constant II, all the multiple- 
byte numbers in the file will be defined as Intel-style objects. If it 
contains MM, they’ll all be defined as Motorola-style objects. You 
might want to have a look at the discussion of Motorola numbers back 
in chapter 3 if you haven’t done so previously. 

The version element in a TIFF header is an integer that will contain 
the value 42, or 2AH. Note, however, that this value might appear in 
either byte of this word, depending on the type of numbers being 
used. 

The offset element in a TIFF header specifies the offset from the 
beginning of the file to the first image file directory; that is, to the first 
list of tags. In a file with one image, this will be the only image file 
directory. The byte order of the offset element will also be dependent 
on the setting of the numbertype element. 

An image file directory consists of an integer defining the number of 
tags in the directory, a number of 12-byte tags, and then a long 
integer. The latter object will be zero if there are no more image file 
directories in the file, or it will contain the offset to the next one. 




Each TIFF tag can be defined by the following data structure. Once 
again, inasmuch as each of the elements in this struct can be either an 
Intel or a Motorola number, you would not actually read a tag this way: 

typedef struct { 

unsigned short int tagnumber; 
unsigned short int type; 
unsigned long length; 
unsigned long offset; 

} TIFFTAG; 

The tagnumber element of a TIFF tag will be one of the many defined 
tag constants, as listed later in this chapter. For example, if this value 
is 256, the tag defines the image width. The tags in a TIFF file are 
constrained to occur in ascending numerical order. 

The type element of a tag defines the type of value the tag will 
represent. The following types are defined: 

1— The tag defines a byte value. 

2— The tag defines an offset to an ASCII string. 

3— The tag defines a short integer. 

4— The tag defines a long integer. 

5— The tag defines the offset to two long integers that form the 
numerator and denominator of a fraction, to specify a rational 
number. 

If the value that a TIFF tag defines requires four or fewer bytes to 
specify, the value itself can be found in the offset element. If it 
requires more than four bytes—an ASCII string is a good example of 
such a tag—the offset element actually does define an offset into the 
file. Decoding a TIFF file usually entails a moderate amount of seeking 
around. 

The length of an object defined by a tag is specified in its length 
element when this information would be pertinent. Specific examples 
of tag values of ambiguous length will turn up in a while. 
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Approaching TIFF tags 

There are several fundamentally contentious issues surrounding the 
information that appears in TIFF tags. While you might find some to 
be far more nettlesome than others, the most commonly encountered 
one appears in the tag called Compression. 

The image in a TIFF file can be compressed using a variety of 
algorithms. Here’s a list of the currently defined ones—it’s worth 
noting that this list used to include several more compression types, 
but that they have recently been declared obsolete: 

1—The image is uncompressed. 

2—The image is compressed using Huffman encoding. 

3—The image is compressed using CCITT group three FAX 
encoding. 

4—The image is compressed using CCITT group four FAX 
encoding. 

5—The image is compressed using LZW string table encoding. 

6—The image is compressed using old JPEG compression. 

7—The image is compressed using 6.0 JPEG compression. 

32773—The image is compressed using MacPaint PackBits 
encoding. 

32946—The image is deflated. 

This list probably deserves some explanation, as some of the 
compression technologies supported by TIFF are a bit exotic. 
Uncompressed images are fairly easy to understand—they’re stored on 
disk just as they would be in memory. Huffman compression applies 
only to two-color image, and is in fact a complex sort of bit string 
table compression that uses a large fixed string table. It was originally 
designed to be implemented in hardware, such as for a FAX machine. 
Huffman compression is remarkably efficient at compressing two-color 
documents, but it’s none too fast when it’s implemented in hardware. 







The CCITT group three and four compressions are variations on 
Huffman compression, the latter being the compression type used by 
contemporary FAX machines. 

The LZW compression supported by TIFF files is identical to that of 
GIF files, except that it can work with images having more than 8 bits 
of color. It’s important to note that the Unisys LZW patent that afflicts 
GIF files also pertains to TIFF files. If your software reads or writes 
TIFF files with LZW compression, Unisys will expect a piece of your 
soul. Should you not have done so previously, have a look at the 
discussion of this situation in chapter 3. Note that you can create the 
TIFF library to be discussed herein without LZW compression included 

MacPaint PackBits compression is a simple run-length compression 
used originally on Macintosh computers. It’s easy to implement but 
tends to fall apart when it’s confronted with complex scanned images. 

The JPEG compression supported by TIFF files is identical to that of 
the JPG files to be discussed in chapter 8. In fact, the TIFF library will 
use the IJG JPEG library to handle it. 

Finally, compressing an image by deflating it uses the same 
compression algorithm as PkWare’s PKZIP archiving package and the 
PNG graphic format to be discussed later in this book. As a rule, 
deflating an image will usually arrive at the smallest possible lossless file 

The TIFF standard allows that TIFF files can be used to store color 
images using either a palette, as in the case of a GIF file, or as RGB 
color pixels, as Targa files do. There is, predictably, a tag to define 
this. In palette color files, the palette information is stored in the tag 
ColorMap, which defines an offset to a lookup table of color values. 
The tables contain RGB values for the colors in the palette being 
defined, but as is often the case in TIFF files, they do so in a format 
only a Martian with a hangover could truly appreciate. 

A TIFF color map consists of all the red values in the palette, followed 
by all the green values, and finally by all the blue values. Each color 
value is stored in a short integer, rather than as a byte. You can 
convert these 16-bit values into the 8-bit values that have appeared in 
other formats by shifting each one right by 8 bits. It’s important to 
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keep in mind, however, that a TIFF color map will occupy twice as 
many bytes in situ than the color maps of other formats. In addition, 
it’s not structured as normal RGB values. 

In reading a TIFF color map, the actual color information will typically 
be located some distance from the tag itself. It will be necessary to 
record the current file position, seek to where the offset element of 
the ColorMap tag indicates, read the palette, and then seek back to 
read the next tag. 

The way image information is stored in a TIFF file—that is, whether 
the file should be regarded as having palette or RGB color and such— 
is defined by the Photometriclnterpretation tag. It can contain one of 
the following values: 

0—The image is a monochrome, single-plane picture in which 
all the set pixels should be regarded as black. 

>* 1—The image is a monochrome, single-plane picture in which 
all the set pixels should be regarded as white. 

2— The image consists of RGB pixels, in which each pixel 
requires three bytes of data. 

3— The image is stored using palette color. 

4— The image is a monochrome picture to be used as 
transparency mask, presumably for the image defined by 
another image file directory in the same TIFF file. 

There are a few things to note about this tag. To begin with, type one 
images are normal monochrome pictures. The actual size and color 
depth of RGB pixels need not be 24 bits of color under TIFF. The 
number of bits of color is defined by the BitsPerSample tag. 

The BitsPerSample tag really defines the number of bits required to 
represent one pixel. This will be 1 for monochrome files, 4 for 16- 
color files, and 8 for 256-color files—it will not be 24 for RGB true 
color files. In fact, it won’t be a value at all—it will be an offset. The 
TIFF specification allows you to define RGB color files in which each 
of the three color indices has a different color depth. As such, the 
offset defined by the BitsPerSample tag will point to a table of three 






integer values, one each defining the number of bits in one of the 
three color components of a pixel. Typically, this will be (8,8,8). It’s all 
but impossible to imagine an application in which you might want to 
define the red component of RGB color pixels to a greater degree of 
precision than the green and the blue. 

The TIFF specification notes of the BitsPerSample tag, “be sure to 
include all three entries. Writing ‘8’ when you mean ‘8,8,8’ sets a bad 
precedent for other fields.” No foolin’. 

The final potentially troublesome party among the frequently 
encountered TIFF tags is one called StripOffsets. This one, too, will 
require a bit of an explanation to properly understand. 

One of the early applications for the TIFF format was in dealing with 
the output of scanners. By their nature, reasonable scanners produce 
large files, good scanners produce gargantuan files, and really 
excellent scanners are almost perfectly Zen-like devices, producing 
files so big that no one has enough memory to contain them and thus 
to judge their true excellence. Allowing that merely owning a really 
excellent scanner was no where near as useful as actually scanning 
something with one, the TIFF format allowed that images could be 
split up into strips. A strip is a horizontal band of image lines such that 
one strip can fit into a reasonable amount of memory, even if the 
entire image it’s part of cannot. 

The TIFF specification defines a strip as ideally being something 
requiring less than 8 kilobytes of memory. 

In some applications of TIFF files, it’s quite forgivable to be decidedly 
less than perfectly Zen-like and ignore this preference of the TIFF 
specification, writing one image as one strip. TIFF files with multiple 
strips take significantly longer to unpack. In single-strip files, the 
StripOffsets tag will point to the first byte of the first line of the image 
data, which should be interpreted based on the constant found in the 
Compression tag in the current image file directory. However, if the 
image in question has been split up into multiple strips, the offset 
value of the StripOffsets tag will, in fact, point to a table of sub-offset 
values, each of which in turn will point to the start of the image data 
for the strip in question. 






Decoding a multiple-strip TIFF file entails some pretty lively seeking 
around, even by TIFF file standards. 


Real-world TIFF files 

Unlike PCX files, for example, all TIFF files are different. As will be 
obvious from the foregoing discussion of tags, you can structure a 
legal TIFF file any way you like. You can add tags to suit your 
requirements or your fancy, and just because no one else has written 
software that’s capable of making sense of the TIFF files you create 
doesn’t make them any less in keeping with the TIFF specification as 
those created by applications you’ve heard of. 

One of the difficulties inherent in writing a really universal TIFF 
decoder is finding examples of suitably obtuse groups of TIFF files to 
test it. For example, if you wanted to make sure that your TIFF reader 
could correctly handle RGB files having differing color depths for each 
of the three color components, you’d have to find some example files 
so afflicted. They probably don’t exist, of course. Probably. 

Commonly used TIFF fags 

The following is a list of TIFF tags you’re likely to encounter in TIFF 
files and might want to use yourself. It’s by no means exhaustive. 

Artist—-315 (13BH)-ASCI1 This tag specifies who created the image. 

BitsPerSampIe—258 (102H)—SHORT This tag defines the number of 
bits per sample. The default is one. 

ColorMap—320 (140H)—SHORT This tag defines the offset to a color 
map for palette color images. 

ColorResporsseCurves—301 (12DH)—SHORT This tag defines three 
color response curves. These curves allow TIFF readers to redefine the 
color in an image, such as to compensate for specific output or display 
hardware. 





Compression—259 (103H)—SHORT This tag defines the type of 
compression used in a TIFF image. The default is one. Its values can be as 
follows: 

^ 1—No compression. 

^ 2—CCITT group 3 one-dimensional modified Huffman run 
length encoding. 

^ 3—CCITT group 3 FAX compression. 

^ 4—CCITT group 4 FAX compression. 

^ 5—LZW compression. 

^ 32773—PackBits run length encoding. 

DafeTime—306 (132)—ASCII This tag defines the date and time at 
which the image was created. 

GrayResponseCorve—291 (123H)—SHORT This tag defines the 
offset of a gray response curve, which modifies the gray levels of a gray 
scale image to compensate for specific output or display hardware. 

GrayRespooseUoIt—290 (122H)—SHORT This tag modifies the gray 
response curve. The default value is two. The recognized values are as 
follows: 

^ 1—Tenths of a unit. 

^ 2—Hundredths of a unit. 

3— Thousandths of a unit. 

4— Ten-thousandths of a unit. 

^ 5—Hundred-thousandths of a unit. 

HostCorripiiter—316 (13CH)—ASCII This tag defines the type of 
computer used to create the image. 

ImageOescriptiors—270 (10EH)—ASCII This tag defines a text 
description of the image. 









ImageLength—257 (101H)—SHORT or LONG This tag defines the 
depth of an image in pixels. 

ImageWidth—256 (100H)—SHORT or LONG This tag defines the 
width of an image in pixels. 

Make—-271 (10FH)—ASCII This tag defines the name of the 
manufacturer of the hardware that digitized the image in question. 

Model—272 (110H)—ASCII This tag defines the model number of the 
hardware that digitized the image in question. 

NewSubfiSeType—254 (FEH)—LONG This tag defines the nature of 
an image in a TIFF file. Its data is made up of a set of 32 flag bits. The 
unused bits are set low. The default is zero, indicating a single, standalone 
image. The bits are defined as follows: 

Bit 0—Set if the image is a reduced version of another image 
stored elsewhere in the file. 

Bit 1—Set if the image is one of several pages stored in this file. 
Bit 2—Set if this image is a transparency mask. 

Photometrlcioterpretatioo—262 (106H)—SHORT This tag indicates 
how an image has been stored. Its values can be as follows: 

0—If the image is black and white, it’s stored reversed. 

>■ 1—If the image is black and white, it’s stored normally. 

>*■ 2—The image uses RGB color. 

3— The image uses palette color. 

4— The image is a black-and-white transparency mask. 

PlanarConflguration—284 (IICH)-SHORT This tag defines whether 
images are stored contiguously or in discrete planes. The default value is 
one. The recognized values are: 

1— The pixels are stored contiguously in a single plane. 

2— The pixels are stored as multiple planes. 








Predictor—317 (13DH)—SHORT This tag defines whether a prediction 
process is used if image data is compressed using LZW encoding. The 
default is one, meaning that no prediction is used. 

ResolutionUnit—296 (128H)—SHORT This tag defines the resolution 
units for the XResolution and YResolution tags. The default value is two. 
The recognized values are: 

1—No absolute unit of measurement is used. 

^ 2—Resolution is defined in inches. 

3—Resolution is defined in centimeters. 

RowsPerStrip—278 (116H)—SHORT or LONG This tag defines the 
number of rows per strip. 

SamplesPerPixel—277 (115H)—SHORT This tag defines the number 
of samples per pixel. The default is one. 

StripByteCounts—279 (117H)-SHORT or LONG This tag defines 
the number of bytes in each strip of an image. 

StripOffsets—273 (IIIH)-SHORT or LONG This tag defines the 
offset to each strip of image information, relative to the start of the file. 

XResolution—282 (11 AH)—RATIONAL This tag defines the number 
of horizontal pixels per ResolutionUnit. 

YResolution—283 (11BH)—RATIONAL This tag defines the number 
of vertical pixels per ResolutionUnit. 

Software—305 (131H)—ASCII This tag defines the name of the 
software used to create the image. 

The TIFLIB library 

Despite its unparalleled complexity—or perhaps merely its perversity— 
the TIFF format is dead easy to work with if you have the services of 
Sam Leffler’s LIBTIFF. Properly configured, it will let your applications 




for TIFF ignore virtually all the complexities of this ferocious little 
entity. I should note, however, that getting LIBTIFF entirely 
comfortable in Windows or Warp is no easy task. Once again, while 
you won’t have to worry about this problem yourself—the version of 
LIBTIFF on the companion disk for this book has been fine-tuned to 
work in these environments—it’s worth keeping this in mind should 
you decide to upgrade to a newer version of the LIBTIFF source code 
at some time in the future. 

The first thing you’ll want to keep in mind about LIBTIFF is that it was 
developed under UNIX and was never intended specifically to run 
under Windows or OS/2. Surprisingly, this poses fewer problems than 
you’d probably expect—the source code is well-written, modular, and 
relatively easy to configure. The functions that tend to be platform- 
specific—for the most part, those dealing with memory 
management—are conveniently located in a single module, which can 
be modified to deal with the vagaries of the environment LIBTIFF 
finds itself in. Once again, you won’t have to get involved with this if 
you use the version of LIBTIFF provided on the companion CD-ROM 
for this book. 

There are several configuration issues that you probably will want to 
be concerned with in using LIBTIFF. Some of them are a bit sneaky— 
and one, as touched on a moment ago, is legal. 

The TIFCONF.H file that accompanies LIBTIFF defines which of the 
TIFF format’s many compression methods will be enabled when you 
compile the library. Here’s what the defines look like: 

#define CCITT_SUPPORT 
#def ine PACKBITS_SUPPORT 
#define LZW_SUPPORT 
#define THUNDER_SUPPORT 
#define NEXT_SUPPORT 
#define JPEG_SUPPORT 
#define ZIP_SUPPORT 

You can disable support for specific compression methods by 
commenting out the appropriate defines before you compile the 
library. 





The CCITT_SUPPORT define enables Huffman, group 3, and group 4 
support in LIBTIFF. This actually presents a problem in using LIBTIFF 
in a 16-bit Windows environment. The fixed bit string decoder tables 
used by these compression methods are exceedingly large objects, and 
a 16-bit application or DLL has a finite data segment size of 64 
kilobytes. The static data represented by the string tables would 
overflow this, and as such CCITT_SUPPORT is undefined if this 
version of LIBTIFF is compiled in a 16-bit environment. 

You might want to undefine LZW_SUPPORT to keep Unisys out of 
your pocket. Having said this, LZW TIFF files are among the most 
commonly used types—doing so could seriously impair the ability of 
your application to import TIFF files from other sources. Methinks this 
was the plan. 

Fve defined JPEG_SUPPORT and ZIP_SUPPORT in this version of 
LIBTIFF; they’re usually undefined by default. The JPEG support 
section of LIBTIFF makes calls to the IJG JPEG library, and the ZIP 
support makes calls to ZLIB, the engine that supports compression 
under PNG. Both of these libraries will be discussed in detail over the 
next two chapters of this book. The PRJ and IDE files for the TIFLIB 
library include all these files; this is one of the reasons why you should 
be sure to preserve the directory structure of the WINBIT and OS2BIT 
directories on the companion CD-ROM for this book when you copy 
them to your hard drive. 

As of this writing, almost no commonly encountered applications 
support these two compression types. 

As with the other libraries in this book, you might find that you don’t 
have any reason to recompile TIFLIB.DLL. Unless you want to disable 
some of the compression methods or you don’t like the writing 
defaults I’ve selected, you can use it as it’s provided on the companion 
CD-ROM for this book. If you do have to rebuild it, here are a few 
things to keep in mind: 

^ It will take a while. Recompiling the whole library under Borland 
C++ 4.52 on a 90 megahertz Pentium machine took me about 
five minutes. 
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You will see some warning messages as the library compiles. 

These can be ignored. As a rule, Windows-based compilers do 
rather more stringent type checking than compilers in other 
environments. 

>- If the IJG JPEG library or the ZLIB library source code are not 
where they’re supposed to be, the library will not compile. 

The Huffman, CCITT group 3, and CCITT group 4 
compression methods will not work in the 16-bit version of the 
library. 

The resulting DLL will be pretty enormous as a 16-bit object— 
plan on something around 400 kilobytes. 

Figure 7-2 illustrates the source code for TIFLIB.CPP—omitting, of 
course, several hundred thousand lines of LIBTIFF. 

/* Figure 7 

TIFF Library 

Copyright (c) 1995 Alchemy Mindworks Inc. 


*/ 


#define _G3STATES_ 

#include <windows.h> 
#include <stdio.h> 
ttinclude <string.h> 
ttinclude <stdlib.h> 
#include <tiff.h> 

#include <tif_fax3.h> 
#include <tiffio.h> 
#include "winbit.h" 


//compression types — they can be: 


// 

//COMPRESSION_NONE 
//COMPRESSION_CCITTRLE 
//COMPRESSION_CCITTFAX3 
//COMPRESSION_CCITTFAX4 
//COMPRESSION_LZW 
//COMPRESSION_JPEG 
//COMPRESSION_PACKBITS 
//COMPRESSION_DEFLATE 


— NO COMPRESSION 
-- HUFFMAN 
-- GROUP 3 FAX 
-- GROUP 4 FAX 

-- LZW (Danger, Will Robinson!) 
-- JPEG 

-- Mac PackBits 
— PNG / ZIP Deflate 


The TIFLIB.CPP source code—deceptively simple. 
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//MONO 

COMPRESSION CAN BE: 

// 

NONE 

// 

LZW 

// 

PACKBITS 

// 

HUFFMAN 

// 

GROUP 3 

// 

GROUP 4 

// 

DEFLATE 

#define 

MON0_COMPRESSION COMPRESSION_DEFLATE 

//PALETTE COMPRESSION CAN BE: 

// 

NONE 

// 

LZW 

// 

PACKBITS 

// 

DEFLATE 

#define 

PAL E TTE_C OMPRE SSION COMPRESSION_DEFLATE 

//RGB COMPRESSION CAN BE: 

// 

NONE 

// 

LZW 

// 

PACKBITS 

// 

JPEG 

// 

DEFLATE 

#define 

RGB_COMPRESSION COMPRESSION_DEFLATE 


#define JPEG_QUALITY 75 
HANDLE hlnst; 

WORD error=NO_ERROR; 

void SwabRGBLine(LPSTR p,int width); 

int checkcmap(TIFF* tif,int n,uintl6* r,uintl6* g,uintl6* b); 

#define CVT(x) ( ( (x) * 255L) / ( (1L«16) -1) ) 

#ifdef WIN32 

#include <g3states.h> 

#endif 

#ifdef _WIN32_ 

ttpragma argsused 

DLL_EXPORT (BOOL) DllEntryPoint(HINSTANCE hlnstance, 

DWORD wDataSeg,LPVOID lpCmdLine) 

{ 

hlnst=hlnstance; 
return(TRUE); 

} 

#else 



#pragma argsused 
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DLL_EXPORT (int) LibMain(HANDLE hlnstance, 

WORD wDataSeg,WORD wHeapSize, LPSTR lpCmdLine) 

{ 

hlnst=hlnstance; 

if (wHeapSize > 0) UnlockData(0); 
return(TRUE); 

} 

#pragma argsused 

DLL_EXPORT (int) WEP(int nParameter) 

{ 

return (TRUE); 

} 

#endif 

DLL_EXPORT (LPSTR) GetFileExtension() 

{ 

return("TIP"); 

} 

DLL_EXPORT (WORD) GetLibraryVersion() 

{ 

return((VERSION « 8) ! SUBVERSION); 

} 

#define DestroyAllObjects(err,success) {\ 

if(tif != NULL) TIFFClose(tif);\ 

if(!success && handle != NULL) GlobalFree(handle);\ 

if(red !=NULL) _TIFFfree(red);\ 

if(green != NULL) _TIFFfree(green);\ 

if(blue != NULL) _TIFFfree(blue);\ 

error=err;\ 

} 

DLL_EXPORT (HANDLE) GetFilelnformation(LPSTR path) 

{ 

TIFF* tif=NULL; 

HANDLE handle=NULL; 
char palette[768]; 

uintl6 *red=NULL,*green=NULL,*blue=NULL; 
long width,depth,bits,samples,bitspersample; 
int i ; 

error=NO_ERROR; 

if ((tif = TIFFOpen(path,"r")) == NULL) { 
DestroyAllObjects(BAD_OPEN,FALSE); 
return(NULL); 

} 

TIFFGetField(tif,TIFFTAG_IMAGEWIDTH,&width); 
TIFFGetField(tif,TIFFTAG_IMAGELENGTH,&depth); 


Figure 7"2 
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Figure 7-2 Continued. 

TIFFGetField(tif,TIFFTAG_SAMPLESPERPIXEL,&samples); 

TIFFGetField (tif, TIFFTAG_BITSPERSAMPLE, Scbitspersample) ; 

TIFFGetField(tif,TIFFTAG_COLORMAP,&red,&green,&blue); 

samples=LOWORD(samples); 

bitspersample=LOWORD(bitspersample); 

bits=samples*bitspersample; 

if(bits==l) GetMonoPalette(palette); 

else if(bits <= 8) { 

if(checkcmap(tif,l<<bitspersample / red,green,blue)==16) { 
for(i=(l<<bitspersample)-1;i>=0;i--) { 

palette[i*RGB_SIZE+RGB_RED]=CVT(red[i]); 
palette[i*RGB_SIZE+RGB_GREEN]=CVT(green[i]); 
palette[i*RGB_SIZE+RGB_BLUE]=CVT(blue[i]); 

i ) 

} 

else { 

for (i= (l«bitspersample) -1; i>=0; i--) { 

palette[i*RGB_SIZE+RGB_RED]=(char)red[i]; 
palette[i*RGB_SIZE+RGB_GREEN]=(char)green[i]; 
palette[i*RGB_SIZE+RGB_BLUE]=(char)blue[i]; 


if((handle=CreateDibHeader(width,depth,palette,bits))==NULL) { 
DestroyAllObj ects(BAD_ALLOC,FALSE); 
return(NULL); 

} 



DestroyAllObjects(NO_ERROR,TRUE); 
return(handle); 

} 

#undef DestroyAllObjects() 

#define PutLine(p,n) hmemcpy(LPBimage(lpbi)+\ 

(DWORD)LPBlinewidth(lpbi)*(DWORD)(LPBdepth(lpbi)-(n)-1),\ 
(p),(DWORD)LPBlinewidth(lpbi)) 

#define DestroyAllObjects(err,success) {\ 

if(tif != NULL) TIFFClose(tif);\ 
if(lpbi != NULL) GlobalUnlock(handle);\ 
if(linebuffer != NULL) FixedGlobalFree(linebuffer);\ 
if(!success && handle != NULL) GlobalFree(handle);\ 
if(red != NULL) _TIFFfree(red);\ 
if(green != NULL) _TIFFfree(green);\ 
if(blue != NULL) _TIFFfree(blue);\ 
error=err;\ 

} 

DLL_EXPORT (HANDLE) ReadGraphicFile(LPSTR path) 
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{ 

TIFF* tif=NULL; 

HANDLE handle=NULL; 

LPBITMAPINFOHEADER lpbi=NULL; 

LPSTR linebuffer=NULL; 
char palette[768]; 

uintl6 *red=NULL,*green=NULL,*blue=NULL; 
long width,depth,bits,samples,bitspersample; 
int i; 

error=NO_ERROR; 

if((tif = TIFFOpen(path,"r")) == NULL) { 

DestroyAllObj ects(BAD_OPEN,FALSE); 
return(NULL); 

} 

TIFFGetField(tif,TIFFTAG_IMAGEWIDTH,&width); 

TIFFGetField (tif, TIFFTAG_IMAGELENGTH, Scdepth) ; 

TIFFGetField(tif,TIFFTAG_SAMPLESPERPIXEL,&samples); 
TIFFGetField(tif,TIFFTAG_BITSPERSAMPLE,&bitspersample); 
TIFFGetField(tif,TIFFTAG_COLORMAP,&red,&green,&blue); 

samples=LOWORD(samples); 
bitspersample=LOWORD(bitspersample); 
bits=samples*bitspersample; 

if(bits==l) GetMonoPalette(palette); 
else if(bits <= 8) { 

if (checkcmap (tif, l«bitsper sample, red, green,blue) ==16) { 

for (i= (l«bitspersample) -1; i>=0; i--) { 

palette[i*RGB_SIZE+RGB_RED]=CVT(red[i]); 
palette[i*RGB_SIZE+RGB_GREEN]=CVT(green[i]); 
palette[i*RGB_SIZE+RGB_BLUE]=CVT(blue[i]); 

} 

} 

else { 

for(i=(lccbitspersample)-1;i>=0;i--) { 

palette[i*RGB_SIZE+RGB_RED]=(char)red[i]; 
palette[i*RGB_SIZE+RGB_GREEN]=(char)green[i]; 
palette[i*RGB_SIZE+RGB_BLUE]=(char)blue[i]; 


if((handle=CreateDib(width,depth,palette,bits))==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

} 

if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(handle)) ==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 


Figure 7-2 
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return(NULL); 


if((linebuffer=FixedGlobalAlloc(LPBlinewidth(lpbi)+1024))==NULL) { 
DestroyAllObj ects(BAD_ALLOC,FALSE) ; 
return(NULL); 


for(i=0;i<(int)depth;++i) { 

if(TIFFReadScanline(tif,linebuffer,i,(int)bits) < 0) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 


if(bits>8L) SwabRGBLine(linebuffer,width); 
PutLine(linebuffer,(unsigned int)i); 


DestroyAllObjects(NO_ERROR,TRUE); 
return(handle); 



} 

#undef DestroyAllObj ects() 

#undef PutLine() 

#define GetLine(p,n) hmemcpy((p),LPBimage(lpbi)+\ 

(DWORD)LPBlinewidth(lpbi)*(DWORD)(LPBdepth(lpbi)-(n)-1),\ 
(DWORD)LPBIinewidth(lpbi)) 

#define DestroyAllObjects(err,success) {\ 

if(tif != NULL) TIFFClose(tif);\ 
if(lpbi != NULL) GlobalUnlock(handle);\ 
if(linebuffer != NULL) FixedGlobalFree(linebuffer);\ 
if(red != NULL) _TIFFfree(red);\ 
if(green != NULL) _TIFFfree(green);\ 
if(blue != NULL) _TIFFfree(blue);\ 
error=err;\ 

} 

DLL_EXPORT (WORD) WriteGraphicFile(LPSTR path, HANDLE handle) 

{ 

TIFF *tif=NULL; 

LPSTR linebuffer=NULL; 

LPBITMAPINFOHEADER lpbi=NULL; 

uintl6 *red=NULL,*green=NULL,*blue=NULL; 

long rowsperstrip; 

long photometric; 

long samplesperpixel; 

long bitspersample; 
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long bpsl; 

unsigned long compression; 
char palette[768]; 
unsigned long width,depth,bits; 
unsigned int i,n,linewidth; 

error=NO_ERROR; 

if((tif=TIFFOpen(path,"w ") )==NULL) { 

DestroyAllObjects(FALSE,BAD_OPEN); 
return(FALSE); 

} 

if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(handle))==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(FALSE); 

} 

width=(long)LPBwidth(lpbi); 
depth=(long)LPBdepth(lpbi); 
bits=(long)LPBbits(lpbi); 

GetDibPalette((LPBITMAPINFO)lpbi,palette); 
linewidth=LPBlinewidth(lpbi); 

if((linebuffer=(LPSTR)FixedGlobalAlloc(linewidth+1024)) == NULL) 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(FALSE); 

} 

switch(bits) { 
case 1: 

samplesperpixel = 1; 
bitspersample = 1; 

photometric = PHOTOMETRIC jyilNISBLACK; 
c ompre s sion=MONO_COMPRES SION; 
break; 
case 4: 
case 8: 

samplesperpixel = 1; 
bitspersample = bits; 
photometric = PHOTOMETRIC_PALETTE; 
c ompr e s sion=PALETTE_COMPRESSION; 
break; 
case 24: 

samplesperpixel = 3; 
bitspersample = 8; 
photometric = PHOTOMETRIC_RGB; 
c ompr e s sion=RGB_COMPRES SION; 
break; 

} 


Figure 7-2 
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bpsl = (long)((((long)bits * (long)width + 15L) » 3) & ~1); 
rowsperstrip = (8 * 1024) / bpsl; 

rowsperstrip=((rowsperstrip+7)>>3)<<3; 


TIFFSetField(tif,TIFFTAG_ 
TIFFSetField(tif,TIFFTAG_ 
TIFFSetField(tif,TIFFTAG_ 
TIFFSetField(tif,TIFFTAG_ 
TIFFSetField(tif,TIFFTAG_ 
TIFFSetField(tif,TIFFTAG, 
TIFFSetField(tif,TIFFTAG_ 
TIFFSetField(tif,TIFFTAG, 
TIFFSetField(tif,TIFFTAG. 
TIFFSetField(tif,TIFFTAG_ 
TIFFSetField(tif,TIFFTAG. 


IMAGEWIDTH,(long)width); 
IMAGELENGTH,(long)depth); 
BITSPERSAMPLE,bitspersample); 
ORIENTATION,ORIENTATION_TOPLEFT); 
COMPRESSION,compression); 
PHOTOMETRIC,photometric); 
SAMPLESPERPIXEL,samplesperpixel); 
ROWSPERSTRIP,rowsperstrip); 
PLANARCONFIG, PLANARC ONFIG_CONTIG) ; 
XRESOLUTION,(double)300); 

YRESOLUTION,(double)300); 


#if RGB_COMPRESSION==COMPRESSION_JPEG 
if(compression==COMPRESSION_JPEG) 

TIFFSetField(tif,TIFFTAG_JPEGQUALITY,JPEG_QUALITY); 

#endif 


if(bits > 1 && bits <=8) { 

n=l<<bits; 

if((red=(uintl6 *)_TIFFmalloc(n*sizeof(uintl6)))==NULL) { 
DestroyAllObj ects(BAD_ALLOC,FALSE); 
return(FALSE); 

} 

if((green=(uintl6 *)_TIFFmalloc(n*sizeof(uintl6)))==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(FALSE); 

} 

if((blue=(uintl6 *)_TIFFmalloc(n*sizeof(uintl6)))==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(FALSE); 

} 


for(i=0;i<n;++i) { 

red[i]=(int)palette[RGB_SIZE*i+RGB_RED] <<8; 
green [i] = (int) palette [RGB_SIZE*i+RGB_GREEN] «8; 
blue [i] = (int)palette [RGB_SIZE*i+RGB_BLUE] «8; 

} 

TIFFSetField(tif,TIFFTAG_COLORMAP,red,green,blue); 

} 



for(i=0;i<depth;++i) { 
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GetLine(linebuffer,i); 

if(bits > 8) SwabRGBLine(linebuffer,width); 

if(TIFFWriteScanline(tif,linebuffer,i,bits) < 0) { 

DestroyAllObj ects(BAD_WRITE,FALSE) ; 
return(FALSE); 

} 

} 

DestroyAllObjects(NO_ERROR / TRUE); 
return(TRUE); 

} 

#undef DestroyAllObjects() 

#undef GetLine() 

DLL_EXPORT (WORD) GetError(LPSTR text) 

{ 

if(text != NULL) lstrcpy(text,GetErrorText(error)); 
return(error); 

} 

DLL_EXPORT (LPSTR) GetCopyright() 

{ 

return("Copyright \251 1995 Alchemy Mindworks Inc."); 

} 

DLL_EXPORT (LPSTR) GetNotice() 

{ 

return( 

"TIFF supports from one to 24 bits of colour.\n\n" 

"Portions of the code in this library are derived from\n" 

"LIBTIFF by Sam Leffler and are:\n" 

"Copyright (c) 1990-1995 Sam Leffler\n" 

"Copyright (c) 1991-1995 Silicon Graphics, Inc.\n\n" 

"This software is based in part on the work of\n" 

"the Independent JPEG Group.\n\n" 

"Portions of this code are\n" 

"Copyright (C) 1995 Jean-loup Gailly and Mark Adler\n\n" 

"WARNING!!!\n" 

"The LZW compression used in the TIFF format has been\n" 

"the subject of a surprise patent by the Unisys corporation.\n" 

"If you implement LZW TIFF in a commercial or shareware\n" 
"application, or in software included with a larger\n" 

"for-profit product, Unisys may demand royalties from you\n" 

"based on the retail price of your product, as well as requiring\n" 
"that you undertake additional accounting on its behalf and\n" 
"possibly adding additional license restrictions to your\n" 

"software.\n\nThis is very nasty.\n\n" 

"Unless you have a compelling reason to do otherwise, it is\n" 
"strongly recommended that you do not use LZW TIFF in your\n" 
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"applications.\n\n" 

"Other TIFF compression types are not affected by this patent."); 

i > 

void SwabRGBLine(LPSTR p, int width) 

{ 

int i,n; 


for(i=0;i<width;++i) { 

n=p[RGB_RED]; 
p[RGB_RED]=p[RGB_BLUE]; 
p[RGB_BLUE]=n; 



p+=RGB_SIZE; 


} 


#pragma warn -par 

int checkcmap(TIFF* tif,int n,uintl6* r,uintl6* g,uintl6* b) 
{ 

while(n-- > 0) 

if(*r++ >= 256 !! *g++ >= 256 !! *b++ >= 256) 
return (16); 

return(8); 

} 

#pragma warn +par 


The first thing you’ll encounter in TIFLIB.CPP is a list of defines for 
compression types. While the complete library will read TIFF files with 
any of the supported compression methods, it must be told specifically 
which method to use when writing them. In this version of the library, 
the writing methods are chosen at compile time and are thereafter 
immutable. There’s something to be said for making these options 
user-configurable in real-world TIFF writers. As we’ll get to in a 
moment, changing the compression method through LIBTIFF is pretty 
painless. 

Note that there are separate compression defines for monochrome 
images, palette color images, and true color images. The CCITT 
compression types can only be used with monochrome images. The 
JPEG compression type is only suitable for use with true color images. 
The LIBTIFF code will complain at run time if you attempt to 
compress an image with an inappropriate method. 
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A complete discussion of everything LIBTIFF will do for you would 
about double the size of this book. There’s extensive documentation 
with the LIBTIFF package if you’d like to experiment with its 
capabilities beyond what the library in this chapter deals with. 

The TIF_WIN3.CPP file in the LIBTIFF directory contains all the 
functions that are specific to Windows or OS/2. You should have no 
cause to dig into this file just to rebuild TIFLIB, but should you want to 
change the way the library behaves, this is where to start. Here’s what 
its contents do: 

_tiffReadProc —This function reads data into a buffer. In this version 
of the library, it calls read for 32-bit Windows and Warp or _hread 
for 16-bit Windows. 

_tiffWriteProc —This function writes data from a buffer. In this version 
of the library, it calls write for 32-bit Windows and Warp or _hwrite 
for 16-bit Windows. 

_tiffSeekProc —This function seeks to a new file location. 
_tiffCloseProc —This function closes a previously opened file. 
TIFFOpen —This function opens a file and allocates a TIFF object. 
_TIFFmalloc —This function allocates memory. 

_TIFFfree —This function frees memory. 

_TIFFrealloc —This function changes the size of a previously allocated 
memory block. 

_TIFFmemset —This function sets memory to a constant value. 
_TIFFmemcpy —This function copies data between buffers. 
_TIFFmemcmp —This function compares the contents of two buffers. 



_TIFFwarningHandler —This is a function pointer to a function that 
will handle warnings. At present, it opens a message dialog and 
displays a text warning message. You might want to change this. 

_TIFFerrorFlandler —This is a function pointer to a function that will 
handle errors. At present it opens a message dialog and displays a text 
error message. You might want to change this. 

The ReadGraphicFile function in TIFLIB makes numerous calls into 
LIBTIFF. It begins by calling TIFFopen to open the source image to be 
read. Allowing that the return value isn’t NULL, it uses TIFFGetField 
to fetch information about the file. Note that TIFFGetField can accept 
a variable number of arguments—when it’s passed 
TIFFTAG_COLORMAP as its second argument, for example, it 
allocates three buffers to hold the palette entries. 

Once the image dimensions, color depth, and palette have been sorted 
out, ReadGraphicFile calls CreateDIB to create a device-independent 
bitmap and then calls TIFFReadScanline to fetch the image lines from 
the file being read. An enormous amount of work will be done by 
TIFFReadScanline, but it all takes place in the dark, sinister 
catacombs of LIBTIFF, and can be ignored. 

The WriteGraphicFile function is hardly more complicated. It uses the 
compression defines from the top of TIFLIB.CPP to decide which 
method it should use to pack the image being written. The TIFFopen 
function will create a TIFF file for writing if its second argument is “w”. 
The TIFFSetField function defines the relevant parameters of the 
image being written. Note that each call to TIFFSetField in effect 
defines a tag to be written to the destination file. Some, like the 
TIFFTAG_XRESOLUTION and TIFFTAG_YRESOLUTION tags, are 
optional. 

With all the preliminaries taken care of, WriteGraphicFile calls 
TIFFWriteScanline once for each line in the source image and closes 
up shop. 





Using TIFF files 

Despite their eccentricities and occasionally ill-tempered dispositions, 
TIFF files can be genuinely useful. They form a flexible, sophisticated 
input path for a variety of applications and, in some cases, offer 
import facilities you can’t arrive at using other formats. 

As a rule, TIFF files do not make a good way to exchange images with 
a large body of other applications, especially if you don’t know what 
the TIFF import filters in question will be expecting. Very few 
commercial applications have TIFF facilities with anything like the 
flexibility of LIBTIFF. 

As of this writing, the LIBTIFF package is free for use in any way you 
like, subject to the conditions imposed by its author. At the moment, 
your sole requirement is to credit its use. Note that if you compile 
LIBTIFF with JPEG or deflate support, you should credit the authors 
of the IJG JPEG library and ZLIB as well. See the GetNotice function 
in TIFLIB.CPP for a suitable set of acknowledgments. 

The most complete reference on the TIFF format is the TIFF 
specification itself, available as the Aldus TIFF Developer’s Kit. It’s 
available from Aldus Corporation, 411 First Avenue South, Seattle, 
Washington, 98104. Aldus can also be reached by phone at (206) 
628-6593. 
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It um so cold I sau< a lawyer with his hands in his own pochets, 

—Graffiti 





HE PNG format can be regarded to some extent as GIF for the 
nineties. It features many of the desirable qualities of GIF—for 
example, it uses very effective lossless compression, and it uses a 
block structure to permit additional information to be stored with an 
image file. On the other hand, it’s not mindlessly flexible like TIFF— 
properly constructed PNG readers can anticipate being able to read all 
PNG files. Its compression method, a hybrid of LZ and Huffman 
compression, is at least typically a bit more effective than the by now 
somewhat antiquated LZW compression used by GIF, and oftentimes 
remarkably so. It supports true color as well as monochrome and 
palette-driven images, and it allows for both single-color and alpha- 
channel transparency. Perhaps most important, however, PNG is 
based on an unencumbered compression technology—using it won’t 
beset you with vampires from Pennsylvania. 


In addition to merely storing pictures, PNG embodies a number of 
high-end options to make it more robust in complex imaging 
applications. In fact, its selection of filters and special-purpose chunks 
for exacting graphic reproduction can be a bit bewildering. Happily, 
they can also be ignored unless you find you need them. The PNG 
format is well designed to allow you to use only as much of it as you 
really require. 


The largest potential catch in using PNG is that it’s relatively new— 
few applications include PNG import and export filters as yet. This 
might well have changed by the time you read this—PNG is a such a 
convenient format to work in that it might well be adopted much more 
readily than GIF was when it first appeared. It’s also worth noting that 
not all the features of GIF turn up in PNG. The PNG format does not 
support multiple images per file as of this writing, for example. 

The acronym PNG stands for “Portable Network Graphics,” and is 
usually pronounced “ping”. 

Figure 8-1 illustrates some example PNG graphics—these are the first 
images released in the PNG format and have come to be used as 
classic test files. 


As with other expandable graphic file formats, such as GIF and TIFF, 
a PNG file consists of a number of blocks, or “chunks,” that can be 
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walked through and expanded as need be. Some chunks, like the ones 
that define a file’s image data or image dimensions, are essential and 
pretty well must be read to unpack the image in question. Others, such 
as optional chunks that store comments, can be ignored if you don’t 
care what’s in them. 

The compression method used by PNG is properly called deflation. 

It’s the default compression method of the PkWare PKZIP package, 
and at the moment, it offers the best possible compression for graphic 
images. In addition, the PNG format lets you fine-tune it a bit—you 










can configure a PNG writer to use varying amounts of aggressiveness 
in compressing a file. More aggressive compression will usually result 
in smaller files, but they can take longer to write. 

It’s important to note in comparing PNG to the JPEG format 
discussed in the next chapter—which also has a variable compression 
factor—that storing an image in a PNG file will always leave you with 
the same image, no matter how you set the compression value. The 
compression used by PNG is lossless, which means that what goes 
into your file will be exactly what comes out of it when it’s unpacked. 

The code to do data deflation is enormously more complex than that 
of the LZW compression used in GIF files. To better compress data, 
deflation actually analyses the data to figure out which of several 
approaches it should take to making it smaller. The few dozen lines of 
code required to perform LZW compression for GIF swells to many 
thousands of lines for a PNG writer. 

Happily, the code to do PNG’s deflation and, in fact, the code to 
manage all the options of a PNG file itself exist as prewritten libraries 
called ZLIB and FIBPNG respectively. We’ll have a look at these in a 
moment. They offer all the functionality you’ll need to make PNG 
work, with almost none of the head bashing that would ordinarily be 
involved in working with a format this complex. They also pretty well 
eliminate the prospect of creating illegal PNG files or of not being able 
to read certain types of PNG files. 

As with TIFF files, you can use these libraries without knowing much 
about how they work. Well-documented and easy to make calls to, 
they reduce the task of dealing with state-of-the-art PNG files to 
something less than the complexity of working with images stored is 
the PCX format. 

The PNGFIB library to be presented in this chapter will illustrate 
reading and writing basic PNG files. There’s a lot more you can do 
with PNG if you want to burrow into it—you might ultimately want to 
get deeper into the libraries upon which it’s based. The complete 
source code for both is included on the companion CD-ROM for this 
book. 







The complete PNG specification is also included on the CD-ROM. 

It’s probably worth noting that the compression used in PNG files has 
an unusual feature: You can define how aggressive you want it to be 
when a PNG file is created. More aggressive compression will usually 
result in smaller PNG files, at the cost of more time required to 
perform the compression. The compression aggressiveness for PNG 
files varies from 1 for relatively poor compression and quick writes to 
9 for very aggressive compression and very slow writes. 

The image stored by a PNG file will not be affected by the 
compression setting—as was mentioned earlier, what goes into a PNG 
file will always be what comes out of it. 


— PNG file structure 



A PNG file consists of a header followed by a succession of chunks. 
The header is an 8-byte signature that looks like this: 

#define PNG_Signature "\x89\x50\x4E\x47\x0D\x0A\xlA\x0A" 

Immediately following the signature is the beginning of the first PNG 
chunk. A PNG chunk looks like this—sort of: 

typedef struct { 

unsigned long length; 
unsigned long type; 

} CHUNK; 

A CHUNK object is followed by whatever data the chunk contains—in 
some cases embodying additional fixed data structures—followed by a 
32-bit CRC check value. 

The aforementioned “sort of” has to with how PNG files store 
numbers. If you happened to be working on a Macintosh or some 
other computer that was powered by a Motorola processor, the 
foregoing structure would be correct. On a PC platform, however, the 
byte order of its numbers would be backward. As such, to convert the 
numbers in a PNG file to real PC numbers, you would have to reverse 
the orders of their bytes. This is something that the PNG library 
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actually takes care of for you—you should have no cause to deal with 
it directly. 

The length value of a PNG chunk only specifies the length of the 
chunks data—it does not include the size of the length value, the type 
value, or the CRC value after the data. However, as these are fixed- 
size elements and are always present in a PNG chunk, it’s easy to 
work out how far to seek ahead in a PNG file if your PNG reader 
encounters a chunk it doesn’t recognize or doesn’t care about. 

The type value of a PNG file is often managed as a long integer, but 
it’s really a string of four ASCII characters. These are usually 
descriptive of the contents of a chunk—at least, they are to the extent 
of what can be said with four characters. The predefined chunk names 
in a PNG file say more than they might seem. If the first character of 
a chunk type string is in uppercase, the chunk is essential to 
unpacking the file. If it’s in lowercase, it’s optional. As such, there’s a 
chunk called IHDR that defines the dimensions and color depth of an 
image. It’s essential, as you couldn’t unpack an image without this 
information. There’s a chunk called tIME that defines the most recent 
modification date of the image. This is optional, as you need not know 
this information just to unpack a picture. 

If the second character in a PNG chunk type is uppercase, the chunk 
is public; that is, it was defined by the PNG specification and should 
be recognizable by any PNG reader that cares to do so. If it’s 
lowercase, the chunk is proprietary to a particular application. Other 
PNG readers will probably want to ignore it. 

The third character in a PNG chunk type field should always be 
uppercase. The possibility of its being lowercase is reserved for future 
expansion. 

If the fourth byte of a PNG chunk type field is lowercase, it’s safe to 
copy the contents of the chunk in question to a new PNG file. If it’s 
uppercase, it’s not safe to do so. This applies to situations wherein the 
contents of an image have been modified and are then to be written to 
a new PNG file. As a simple example, you would not want to copy the 
contents of a tIME chunk to a new PNG file after the image has been 
modified—a new tIME chunk reflecting the new modification date 







would be required. There’s a chunk called tEXt that defines text 
comments for an image. This chunk could be copied. 

Every PNG file must include a small set of essential chunks, as follows: 

SHDR IHDR is the image header chunk. It contains the following data 
structure: 

typedef struct { 
long width; 
long depth; 
char bits; 
char colortype; 
char compressiontype; 
char filtertype; 
char interlacetype; 

} IHDR; 

The width and depth fields of an IHDR structure define the 
dimensions in pixels of the image. The bits field defines the color 
depth per pixel for palette-driven images or per sample for true-color 
images. A true color image typically has three samples per pixel. This 
field can contain values of 1, 2, 4, 8, and 16. 

The colortype field defines what sort of image pixels are being used. If 
colortype & 0x01 is true, the image is palette-driven. If colortype & 
0x02 is true, the image is true color. If colortype & 0x04 is true, the 
image has an alpha-channel component—alpha channels were dealt 
with earlier in chapter 6. Note that a true color image in a PNG file 
can have either conventional 3-byte RGB pixels or 2-byte high-color 
pixels. 

The filtertype field defines which filter type should be used to post¬ 
condition the image being unpacked. At present, this field can only 
contain zero for adaptive filtering. Once again, this is something that 
the PNG library will take care of for you. 

The interlacetype field defines whether the image is stored normally 
or interlaced. It will be zero for no interlacing and one for Adam7 
interlacing. I’ll deal with interlacing later in this chapter. 





PLTE PLTE is the palette chunk. It contains up to 256 three-byte palette 
entries. Colors in a PNG file are stored in the order red, green, and blue. 
Color palettes are optional for true color images—if a PLTE chunk is 
present in a true color file, it represents a suitable palette to remap or 
dither the image to. 

IDAT I DAT is the image chunk. This chunk contains the compressed 
image data for the file. One potential complexity in PNG files is that a 
single image can be split up into multiple IDAT chunks. 

IEND I END is the image trailer chunk. This chunk is the last chunk in a 
PNG file and signals the end of the data. 

There are quite a few additional standard chunks, or ancillary chunks, 
available to PNG writers. These are all optional—PNG writers need 
not include them and PNG readers should not count on their being 
present. The PNG library will take care of creating these chunks for 
you if you want it to, but you must explicitly instruct it to do so. 
Consult the PNG specification for a more complete discussion of these 
chunks. 

The following are some of the more commonly encountered ancillary 
chunks. Keep in mind that all the multiple-byte objects in these chunks 
use Motorola-style numbers that must be reversed for use on a PC. 

bKNO bKND is the background color chunk. If the image being 
compressed includes a palette, this chunk contains one byte that defines 
the palette index value to be used as a background color. If the image is 
a gray scale graphic, this chunk contains two bytes—one short 
integer—that defines the background gray level. If the image is a true 
color graphic, this chunk contains six bytes—three short integers—that 
specify the red, green, and blue values for the background color. 

gAMA gAMA is the gamma correction chunk. This chunk contains four 
bytes—one long integer—-that defines the gamma correction of the camera 
or scanner that created the image. A value of 100,000 represents a 
gamma of 1.0. 

sBIT sBIT is the significant bits chunk. A PNG file can only store images 
having 1, 2, 4, 8, 16, or 24 bits of color. Images with intermediate color 





depths are promoted to the next highest legal value. This chunk can be 
used to store the actual color depth. It will contain one byte for gray scale 
images and three bytes for true color and palette driven images. 

fEXt tEXt is the text chunk. Text always consists of a key word, followed 
by a null byte, followed by some additional text. 

tIME tIME is the modification time chunk. This chunk consists of the 
following data structure: 


typedef struct { 

unsigned short int year; 

char month; 

char day; 

char hour; 

char minute; 

char second; 

} TIME; 


The year value must be the complete date, such as 1996, rather than 
just 96. The second value can run from 0 through 60 to allow for 
leap seconds. 


You can also create proprietary chunks in a PNG file; that is, chunks 
that only make sense to your applications. There’s a list of special 
purpose PNG chunks as of this writing included on the companion 
CD-ROM for this book. You can propose additional chunks by sending 
e-mail to png-info@uunet.uu.net. 

Interlacing in PNG files 

Interlaced images offer applications that download graphics and 
display them as they’re downloaded a way to present a coarse 
approximation of the complete image fairly early on in the download, 
allowing, for example, a user to abort the download if the image in 
question doesn’t look interesting. While this was a somewhat exotic 
consideration for bitmapped graphics a few years ago, it has become 
fairly common with the use of graphic images on the World Wide Web 






What interlacing really does is to download the pixels of an image in 
an order other than the one you’d probably store them in for a 
conventional graphic. Figure 8-2 illustrates how this works—this 
interlace pattern is actually the one used by GIF rather than the 
Adam7 interlace order used by PNG, but it more readily demonstrates 
how an interlaced image starts off with relatively little detail and fills in 
the blanks as it goes. 



Simple interlacing. Political correctness will have to wait. 


The interlaced image illustrated in Fig. 8-2 was stored with its lines 
out of order, such that they could be unpacked out of order and 
written to your screen that way. The decoding software, knowing the 
order they’re intended to appear in, can write each line to the correct 
line of the screen the image is being displayed on. 

An interlaced image doesn’t store a table of values to indicate where 
each line or pixel goes—it doesn’t have to. Interlaced graphic formats 
define an algorithm that translates line or pixel coordinates as they’re 
decoded into screen coordinates. As the same algorithm is used to 
pack and unpack an interlaced image, it will be automatically 
deinterlaced when it’s unpacked. 

The interlacing method used for GIF files works with complete lines. The 
interlacing method used by PNG files works with individual pixels. This 
will usually present you with a recognizable image earlier in the 
downloading process, all other things being equal, but it confronts a 
PNG reader with several important consequences. Specifically: 
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The interlacing algorithm must be considerably more complex. 

Windows and OS/2 impose a fair bit of overhead on an 
application that wants to begin writing one or more pixels to the 
screen. This overhead must be undertaken to write one line or 
one pixel. This makes PNG files a lot slower to display under 
Windows or Warp. 

The juggling of pixels in an interlaced image tends to break up 
runs of consecutive pixels, meaning that interlaced PNG files will 
usually be larger than non-interlaced PNG files. 


Figure 8-3 illustrates the interlacing method of an interlaced PNG file. 
Figure 8-3 /* 

PNG Library 

Copyright (c) 1995 Alchemy Mindworks Inc. 


*/ 

#include <windows.h> 

#include <stdio.h> 

#include <string.h> 

#include <stdlib.h> 

#include <zlib.h> 

#include <png.h> 

#include "winbit.h" 

// Compression factor -- this should be: 

// 1 -- fastest writes, worst compression 
// 9 -- slowest writes, best compression 
// Z_DEFAULT_COMPRESSION (6) — somewhere in the middle 
#define PNG_COMPRESSION Z_DEFAULT_COMPRESSION 

int PNGReadlmage(png_struct *png_ptr,HPSTR image, 

unsigned long bytes,unsigned long depth,int pass); 

HANDLE hlnst; 


WORD error=NO_ERROR; 

#ifdef WIN32 

#pragma argsused 

DLL_EXPORT (BOOL) DllEntryPoint(HINSTANCE hlnstance, 
DWORD wDataSeg,LPVOID lpCmdLine) 

{ 

hlnst=hlnstance; 



The interlacing method of an interlaced PNG file. 
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return(TRUE); 

} 

#else 

#pragma argsused 

DLL_EXPORT (int) LibMain(HANDLE hlnstance, 

WORD wDataSeg,WORD wHeapSize, LPSTR lpCmdLine) 

{ 

hlnst=hlnstance; 

if (wHeapSize > 0) UnlockData(0); 
return(TRUE); 

} 

#pragma argsused 

DLL_EXPORT (int) WEP(int nParameter) 

{ 

return (TRUE); 

} 

#endif 


DLL_EXPORT (LPSTR) GetFileExtension() 

{ 

return("PNG"); 

} 

DLL_EXPORT (WORD) GetLibraryVersion() 

{ 

return((VERSION << 8) | SUBVERSION); 

} 

#define DestroyAllObjects(err,success) {\ 

if(fp != NULL) fclose(fp);\ 

if(!success && handle != NULL) GlobalFree(handle);\ 
if(png_ptr != NULL) free(png_ptr);\ 
if (inf o__ptr != NULL) f ree (inf o_ptr) ; \ 
error=err;\ 

} 

DLL_EXPORT (HANDLE) GetFilelnformation(LPSTR path) 

{ 

FILE *fp=NULL; 

HANDLE handle=NULL; 
png_struct *png_ptr=NULL; 
png_info *info_ptr=NULL; 
char palette[768]; 
unsigned int width,depth,bits; 

Initialize(); 

if((fp=fopen(path,"rb"))==NULL) { 

DestroyAllObjects(BAD_OPEN,FALSE); 
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return(NULL); 

I } 

if((png_ptr=(png_struct *)malloc(sizeof(png_struct)))==NULL) { 
DestroyAllObj ects(BAD_ALLOC,FALSE); 
return(NULL); 

i } 

if((info_ptr=(png_info *)malloc(sizeof(png_info)))==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

} 

if(setjmp(png_ptr->jmpbuf)) { 

DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

i } 

png_read_init(png_ptr); 
png_info_init(info_ptr); 
png_init_io(png_ptr,fp); 
png_read_info(png_ptr,info_ptr); 

width=info__ptr->width; 

depth=info_ptr->height; 
bits=info_ptr->bit_depth; 
if(bits <= 8) 

memcpy (palette, info_ptr->palette, RGB_SIZE* (l«bits) ) ; 
else GetOrthoPalette(palette); 

if((handle=CreateDibHeader(width,depth, 
palette,bits))==NULL) { 

png_read_destroy(png_ptr,NULL,NULL); 

DestroyAllObj ects(BAD_ALLOC,FALSE); 
return(NULL); 

} 

png_read_destroy(png_ptr,NULL,NULL); 

De s t royAl1Obj ec t s(NO_ERROR,TRUE); 
return(handle); 



#undef DestroyAllObj ects() 

#define PutLine(p,n) hmemcpy(LPBimage(lpbi)+\ 

(DWORD)LPBlinewidth(lpbi)*(DWORD)(LPBdepth(lpbi)-(n)-1),\ 
(p),(DWORD)LPBlinewidth(lpbi)) 

#define DestroyAllObjects(err,success) {\ 

if(fp != NULL) fclose(fp);\ 
if(png_ptr != NULL) free (png__ptr) ; \ 
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if(info_ptr != NULL) free(info_ptr);\ 
if(lpbi != NULL) GlobalUnlock(handle);\ 

if(row_pointers !=NULL) FixedGlobalFree(row_pointers);\ 
if(!success && handle != NULL) {\ 

GlobalFree(handle);\ 
handle=NULL;\ 

}\ 

error=err;\ 

} 

DLL_EXPORT (HANDLE) ReadGraphicFile(LPSTR path) 

{ 

unsigned char ** row_jpointers=NULL; 

LPBITMAPINFOHEADER lpbi=NULL; 

FILE *fp=NULL; 

HANDLE handle=NULL; 
png_struct *png_ptr=NULL; 
png_info *info__ptr=NULL ; 
char palette[768]; 

unsigned int width,depth,bits,pass; 

ttifndef _WIN16_ 

unsigned int i; 

#endif 

Initialize(); 

if((fp=fopen(path,"rb"))==NULL) { 

DestroyAllObjects(BAD_OPEN,FALSE); 
return(NULL); 


} 

if((png_ptr= 

(png_struct *)malloc(sizeof(png_struct)))==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

} 

if((info_ptr= 

(png_info *)malloc(sizeof(png_info)))==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

} 

if(setjmp(png_ptr->jmpbuf)) { 

DestroyAllObjects(BAD_FILE,FALSE); 
return(NULL); 

} 

png_read_init(png_ptr); 

png_info_init(info_ptr); 

png_init_io(png_ptr,fp); 

png_read_info(png_ptr,info_ptr); 


Figure 8-3 
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width=info_ptr->width; 
depth=info_ptr->height; 
bits=info_ptr->pixel_depth; 

if(bits <= 8) 

memcpy (palette, info_ptr->palette, RGB_SIZE* (l«bits) ) ; 
else GetOrthoPalette(palette); 

pass=png_set_interlace_handling(png_ptr); 

png_start_read_image(png_ptr); 
png_read_update_info(png_ptr,info_ptr); 

if(info_ptr->color_type == PNG_COLOR_TYPE_RGB || 

info_ptr->color_type == PNG_COLOR_TYPE_RGB_ALPHA) 
png_se t_bgr(png_p tr); 

if((handle=CreateDib(width,depth,palette,bits))==NULL) { 
png_read_des troy(png_ptr,NULL,NULL); 

DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

i ) 

if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(handle)) ==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

! } 

#ifdef _WIN16_ 

if(!PNGReadlmage(png_ptr,LPBimage(lpbi), 

(long)LPBlinewidth(lpbi),(long)LPBdepth(lpbi),pass)) { 

DestroyAllObj ects(BAD_ALLOC,FALSE); 
return(NULL); 

j } 

I #else 

if((row_pointers=(unsigned char**) 

FixedGlobalAlloc(depth*sizeof(unsigned char*)))==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

} 


for(i=0;i<depth;++i) 

row_pointers[depth-i-1]=(unsigned char *)LPBimage(lpbi)+ 
(long)i*(long)LPBlinewidth(lpbi); 

png_read_image (png__ptr , row__pointers) ; 

#endif 

png_read_end(png_ptr,NULL); 



png_read_destroy(png_ptr,NULL,NULL); 
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DestroyAllObjects(NO_ERROR,TRUE); 
return(handle); 

} 

#undef DestroyAllObjects() 

#ifdef WIN16 

void png_read_row(png_struct *png_ptr, 
png_byte how, png_byte *dsp_row) ; 

int PNGReadlmage(png_struct *png_ptr,HPSTR image, 

unsigned long bytes,unsigned long depth,int pass) 

{ 

LPSTR linebuffer; 

HPSTR pd; 
png_uint_32 i; 
int j ; 

if((linebuffer=(LPSTR)FixedGlobalAlloc(bytes+1024)) !=NULL) { 
for(j=0;j<pass;j++) { 

pd=image+bytes *depth; 
for(i=0L;i< png_ptr->height;i++) { 

pd-=bytes; 

hmemcpy(linebuffer,pd,bytes); 
png_read_row(png_j?tr,linebuffer,NULL); 
hmemcpy(pd,linebuffer,bytes); 

} 

} 

FixedGlobalFree(linebuffer); 
return(TRUE); 

} 

return(FALSE); 

} 

#endif 

#define DestroyAllObjects(err,success) {\ 

if(fp != NULL) fclose(fp);\ 

if (fp ! = NULL ScSc ! success) DeleteFile (path) ; \ 
if(lpbi != NULL) GlobalUnlock(handle);\ 
if(bp != NULL) FixedGlobalFree(bp);\ 

if(linebuffer !=NULL) FixedGlobalFree(linebuffer);\ 
if(row_pointers != NULL) FixedGlobalFree(row_pointers);\ 
error=err;\ 

} 

DLL_EXPORT (WORD) WriteGraphicFile(LPSTR path, HANDLE handle) 

{ 

unsigned char **row__pointers=NULL; 

LPSTR linebuffer=NULL; 

LPBITMAPINFOHEADER lpbi=NULL; 

LPSTR bp=NULL; 

FILE *fp=NULL; 
png_struct *png_ptr; 


Figure 8-3 
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png_info *info_ptr; 

char palette [768] ; 

unsigned int i; 

if((fp=fopen(path,"wb"))==NULL) { 

DestroyAllObj ects(BAD_CREATE,FALSE) ; 
return(FALSE); 

j ) 

if((png_ptr=(png_struct*)malloc(sizeof(png_struct)))==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(FALSE); 

j ) 

memset((char*)png_ptr,0,sizeof(png_struct)); 

if((info_ptr=(png_info*)malloc(sizeof(png_info)))==NULL) { 
DestroyAllObj ects(BAD_CREATE,FALSE); 
return(FALSE); 

i } 

memset((char*)info_ptr,0,sizeof(png_info)); 

if (set jmp (png_j?tr->jmpbuf) ) { 

png_write_destroy(png_ptr); 

DestroyAllObjects(BAD_WRITE,FALSE); 
return(FALSE); 

i ) 

png_info_init(info_ptr); 

png_write_init(png_ptr); 

png_init_io(png_ptr,fp); 

png_set_compression_level(png_ptr,PNG_COMPRESSION); 

if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(handle))==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(FALSE); 


GetDibPalette((LPBITMAPINFO)lpbi,palette); 

info_ptr->width=LPBwidth(lpbi); 
info_ptr->height=LPBdepth(lpbi); 
if(LPBbits(lpbi) <= 8) { 

info_ptr->bit_depth=LPBbits(lpbi); 

inf o_ptr->color_type=PNG_COLOR_TYPE_PALETTE; 

info_ptr->channels = 1; 
info_ptr->valid |= PNG_INFO_PLTE; 
info_ptr->palette=(png_color_struct*)palette; 
info_ptr->num_palette = l«LPBbits (lpbi) ; 
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} 

else { 

info_ptr->bit_depth=8; 

in f o_p t r->c o1or_type=PNG_COLOR_TYPE_RGB; 
info_ptr->channels = 3; 
png_set_bgr(png_ptr); 

} 

png_write_info(png_ptr,info_ptr); 

#ifdef _WIN16_ 

if((linebuffer= 

(LPSTR)FixedGlobalAlloc(LPBlinewidth(lpbi)+1024)) == NULL) { 
png_write_destroy(png_ptr); 

DestroyAllObjects(BAD_ALLOC,FALSE); 
return(FALSE); 

} 

for(i=0;i<LPBdepth(lpbi);++i) { 

hmemcpy(1inebu f f er, 

LPBimage(lpbi)+(long)(LPBdepth(lpbi)-i-1)* 

(long)LPBlinewidth(lpbi),LPBlinewidth(lpbi)); 
png_write_rows (png_ptr, (unsigned char **) Sclinebuffer, 1) ; 

} 

#else 

if((row_pointers=(unsigned char**) 

FixedGlobalAlloc(LPBdepth(lpbi)* 
sizeof(unsigned char*)))==NULL) { 

DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

} 

for(i=0;i<LPBdepth(lpbi);++i) 

row_pointers[LPBdepth(lpbi)-i-1]= 

(unsigned char *)LPBimage(lpbi)+ 

(long)i*(long)LPBlinewidth(lpbi); 

png_write_image (png__ptr, row_pointers) ; 

#endif 

png_write_end(png_ptr,info_ptr); 
png_write_destroy(png_ptr); 


DestroyAllObjects(NO_ERROR,TRUE); 
return(TRUE); 

} 

#undef DestroyAllObj ects() 


Fig 


DLL_EXPORT (WORD) GetError(LPSTR text) 
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\ i 

if(text != NULL) lstrcpy(text,GetErrorText(error)); 
return(error); 

; } 

DLL_EXPORT (LPSTR) GetCopyright() 

I { 

return("Copyright \251 1995 Alchemy Mindworks Inc."); 

i } 

DLL_EXPORT (LPSTR) GetNotice() 

{ 

return( 

"PNG supports from one to 24 bits of colour.\n\n" 
"Portions of this code are\n" 

"Copyright (C) 1995 Jean-loup Gailly and Mark Adler\n\n" 
"Portions of this code are\n" 

"Copyright (c) 1995 Guy Eric Schalnat, Group 42, Inc.\n" 
"with contributions from Dave Martindale, \n" 

"Guy Eric Schalnat and Tim Wegner." 



A PNG reader must be able to correctly unpack interlaced PNG files, 
although it’s not compelled to display them in interlaced order. The 
PNG library to be presented in the next section of this chapter does 
what most PNG readers will do: It unpacks the interlaced pixels into a 
large buffer—the device-independent bitmap being created—and then 
displays the images normally. It writes non-interlaced PNG files. 

While you probably won’t have to get involved with interlaced PNG 
files directly unless you plan to write an online PNG viewer, it’s 
important to keep in mind that they do exist and will turn up from 
time to time. 

The PNGL1B library 

As with the TIFF library in the previous chapter, PNGLIB is vastly 
simpler than it probably has a right to be because the libraries it links 
to do most of the work. As we’ll get to in a moment, said libraries 
have a bit of a problem when they’re asked to run as part of a 16-bit 
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application, and reading a PNG file must be handled slightly differently 
in this case. 

As with LIBTIFF, the LIBPNG library that does all the work is a 
sophisticated, flexible entity with a lot of functionality you won’t need 
to get up close and personal with just to read and write simple images. 
This section will discuss the library calls required to deal with PNG 
files in the context of the applications in this book—you might want to 
have a more extensive look at LIBPNG if you want to do more with 
the PNG format. 

The current version of LIBPNG and ZLIB as of this writing are 
included on the companion CD-ROM for this book. 

The LIBPNG and ZLIB libraries want to use the C language streamed 
file functions. The ReadGraphicFile function in PNGLIB begins by 
calling fopen to open the source file. It allocates two objects that the 
PNG library wants to use: png_struct and pngjnfo. It then calls 
setjmp, something that hasn’t turned up previously. 

The setjmp function is decried in some software development circles 
almost as vehemently as are gotos. Once called, it preserves the 
machine state as it was when the call was made in the png_ptr- 
>jmpbuf object. Thereafter, if something goes wrong in the process of 
unpacking a PNG file, the library can issue a longjmp call. This will 
cause the program to stop and magically resume execution at setjmp, 
restoring the preserved machine state. The first time setjmp is called, 
it will return zero, and ReadGraphicFile will continue with what it’s 
doing. If it’s called by a call to longjmp, it will return an error code, 
and ReadGraphicFile will terminate. 

This is a bit funky, but it allows complex functions like the ones in 
LIBPNG to terminate abnormally with a minimum of fuss. 

There are four functions in LIBPNG that must be called before a PNG 
file can be read, to wit, png_read_init, pngjnfojnit, pngjnitjo and 
png_readJnfo. Having done so, the pngjnfo object will contain 
information about the PNG file to be read. The ReadGraphicFile 
function can now create a device-independent bitmap with a call to 
CreateDIB. 






The simplest way to read a PNG file is to call png_readjmage. Its 
approach to reading a bitmap is a bit unusual, however. Rather than 
accepting a pointer to the base of a buffer in which to store the 
bitmap, it accepts a pointer to a table of pointers, with one entry for 
each line in the image to be read. It fills in each line—deinterlacing the 
image being read in the process—and returns. 

This isn’t particularly difficult to deal with unless LIBPNG finds itself in 
a 16-bit Windows environment. Because it’s a DLL, PNGLIB defaults 
to using far pointers, which have a maximum offset of 64 kilobytes. 
Bitmaps much larger than this are by no means uncommon. One way 
around this would be to cast every affected pointer in LIBPNG and 
ZLIB to huge —this would be a serious undertaking to do correctly and 
would slow the whole works down enormously. The other approach— 
and incidentally the one that’s been used here—is to rewrite 
png_read_image. 

If PNGLIB is compiled as a 32-bit library, it allocates space for a table 
of pointers, makes each pointer point to one line of its device¬ 
independent bitmap and calls png_readjmage. In a 16-bit version of 
the library, ReadGraphicFile calls PNGReadlmage, a function 
declared in PNGLIB.CPP. This, in turn, makes calls into LIBPNG. It’s 
declared right after ReadGraphicFile in Fig. 8-4. 

The PNGReadlmage function really just duplicates the internal 
workings of png_read_image, but it does so in a way that allows 
png_read_row, where all the work is done, to be passed a far pointer 
to single line buffer, rather than a huge pointer into the device¬ 
independent bitmap under construction. It looks to be a bit more 
complex than it should have to be—keep in mind that each line might 
be written to multiple times if the image being unpacked is interlaced. 
As such, each line is copied from the device-independent bitmap to 
linebuffer, passed to png_read_row, and then copied back to the 
buffer. 

The WriteGraphicFile function of PNGLIB.CPP is ever simpler than 
the file reader. It creates its destination file and allocates png_struct 
and pngjnfo objects as before. Note that, in addition to the 
aforementioned initialization calls into LIBPNG, it also calls 
png_set_compressionJevel to set the degree of compression 
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aggressiveness. In this version of the library, the argument to this 
function is set as PNG_COMPRESSION, defined at the top of 
PNGLIB.CPP. In a real-world application of PNG files, you’d probably 
want to make this value user-definable. 

As with reading a PNG file, the LIBPNG library offers a very 
convenient interface to pack an entire bitmap through a call to 
png_write_innage. Once again, this won’t work in a 16-bit 
environment because of the limitations of far pointers. As such, the 
WriteGraphicFile will use png_write_image if it’s compiled as a 32- 
bit DLL, or it will call png_write_rows once for each line of the 
source image if it’s compiled to work in a 16-bit environment. The 
latter gets around the problem, albeit with a noticeable speed penalty. 

This version of WriteGraphicFile always writes PNG files as 
noninterlaced images. It’s a simple matter to make the 32-bit version 
write interlaced files—somewhat more hacking will be called for to 
make this workable under 16 bits. 

It’s worth noting that, at present, the default ZLIB will not compile 
quite correctly to create legal PNG files. The problem is in ZCONF.H, 
in the WINBIT\PNG\ZLIB directory. The value of the MAX_WBITS 
must be changed. Because ZLIB is also used by TIFLIB in the previous 
chapter, I’ve set it up here to compile correctly for working with PNG 
files if the constant PNG is defined. Should you have cause to recreate 
the PRJ or IDE files for PNGLIB, make sure you define PNG. 



Using PNG files 


While the GIF format will probably be with us for a while longer, 
applications that support PNG are becoming more and more 
common. If you plan to write software that will deal with multiple file 
formats, PNG should arguably be one of them. 


As of this writing, both LIBPNG and ZLIB are available at no cost for 
your use, subject only to your acknowledging their creators in the 
documentation for your software. A suitable acknowledgment can be 
found in the GetNotices function of PNGLIB. 
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S has been touched on at several times throughout this book, 
bitmapped graphics with enough resolution and color depth to 
be interesting take up a lot of space. True color bitmaps—which are 
the most attractive images, all other things considered—can take up 
enormous amounts of space without half trying. Even cosmically 
sneaky compression algorithms, such as the one used by PNG files, 
rarely make a significant dent in complex scanned true color images. 

The problem with compressing scanned true color images is that such 
pictures look a lot like reality, and reality is analog. A digitized view of 
an analog reality frequently embodies lines of pixels in which each 
pixel is just a bit different from its neighbor. As image compression 
algorithms ultimately work by looking for redundant data, these minor 
variations in pixel color are enough to prevent such images from being 
effectively compressed. 

In high-end imaging applications, huge high-resolution true color 
image files are an inescapable part of the cosmic scheme of things, 
because these applications require all the detail they can muster. In 
many cases, however, it would be handy to have the color capabilities 
of a true color image, even if this level of detail resolution isn’t really 
called for. 

Consider an image of a polar bear in a snowstorm. Most of the pixels 
in such a picture would be white, or nearly so. Because both polar 
bears and snowstorms are analog phenomena, they’d probably 
embody lots of different shades of white. You might look at such a 
picture and decide that all the fine gradations of white don’t add much 
to it, and allow that some of the details could be lost without really 
upsetting the image. 

Graphics with fewer details compress more readily. One way to go 
beyond what conventional compression techniques allow for, then, 
would be to create an algorithm that selectively discarded a 
predetermined amount of image detail, then compressed the resulting 
details as effectively as possible. This is in essence what a JPEG file 
does. 

Surprisingly, especially in dealing with moderate resolution images, 
you can usually throw away a significant amount of detail before the 












image in question starts looking noticeably worse for the experience. 
One of the potential catches in using JPEG, however, is that the point 
where things start looking unacceptably ugly varies between images 
and, to some extent, between the people who look at them. 
Compressing images into JPEG files is, to some extent, subjective. 

It’s also worth noting that JPEG works well on photorealistic images— 
it can trash enough detail in scanned photographs to arrive at a 
respectable level of compression without making the pictures look 
noticeably worse. It fares much less well when it’s presented with line 
art, such as text. Even a slight reduction in the detail level of a line art 
image stored in a JPEG file will usually result in a noticeable 
degradation of the image quality. 

In packing a JPEG image, a JPEG writer will be set up with a quality 
factor of between one and 100. At a quality factor of one, a JPEG 
writer will discard almost all the details in a graphic and write an 
image of industrial waste that is having its identity protected on the 
eleven o’clock news—no matter what the source image happened to 
be. At a quality factor of 100, a JPEG writer will hardly touch the 
contents of the bitmap it’s being asked to store. Of course, it will 
probably hardly compress it, as well. Intermediate values represent a 
trade off between these extremes—a quality factor of 75 is usually a 
good starting point when you’re writing JPEG files of modest 
resolution. 

Figure 9-1 illustrates the effects of varying quality factors on an image. 

There are a few important things to keep in mind about the quality 
factor of a JPEG file. To begin with, it seems as if a quality factor of 
100 should store JPEG images with absolutely no loss of detail; that 
is, such that what went into a JPEG file would be identical to what 
came out when the file was read. It would be nice if this were the 
case, but it’s not. Even at a quality factor of 100, JPEG files do 
mangle the images they store to a tiny degree. 

Secondly, the quality factor value isn’t an absolute measure of 
anything—it doesn’t, for example, represent the percentage of details 
lost in JPEG compression or the absolute compression ratio for the 
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final file. It’s only a relative indicator of how much detail a JPEG 
writer will discard. 

You should also keep in mind that the detail losses in a JPEG file are 
cumulative. This means that if you write an image to a JPEG file, read 
it back and then write it again, the second file will have lost twice as 
many details as the first one. In using JPEG files to create compact 
images for downloading or for use on Web pages, you should do all 
your image manipulation in another format—such as BMP, Targa, or 
PNG—and only write your images to JPEG as the final step of the 
process. 

To be really precise and technical about the matter, JPEG is not a 
graphic file format. It’s a compression algorithm. It appears in several 
file formats, including TIFF, as was discussed earlier in this book. 
There are, of course, files that are referred to as being “JPEG files”— 
technically, these are in a format called JFIF. There’s no real need to 
know this—such files are always given the extension JPG, for JPEG. 
Presumably, JPEG is easier to pronounce without excessive spitting. 

Note that JPEG files that have been created in environments that 
allow for more complex file names than DOS does often have the file 
extension JPEG, rather than JPG. For example, you might encounter 
a file called Nice-Assembly-of-Butterflies.JPEG on a system running 
UNIX, on a Macintosh, or under Windows 95. Such files are typically 
truncated to legal DOS file names when they make their way to a PC. 
In this case, the file would become NICE-ASS.JPE—this would be 
politically incorrect and likely to get you an afternoon of corporate 
personality reorientation were it to be found on your hard drive at 
work. It would also result in an incorrect DOS file name. A JPEG 
reader that relies on file name extensions should allow for JPE files. 

The JPEG JFIF file format—the one to be discussed in this chapter 
and the one that’s found all over the known universe with the 
extension JPG—only allows for two types of images: 24-bit true color 
and eight-bit gray scale. Monochrome and palette-driven images 
cannot be stored directly in a JPEG file. As is the case with the JPEG 
library to be discussed in this chapter, lesser bitmaps must be 
promoted to one of these supported color depths to be stored in a 
JPEG file. 
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Most images stored in JPEG files are true color graphics. While the 
JPEG library to be dealt with in this chapter will correctly read gray 
scale JPEG files, let’s ignore them for the time being. 

Because what goes into a JPEG file will always be a 24-bit graphic, it’s 
reasonable to expect what comes out of one to have the same color 
depth. The catch in this is that many PCs can’t deal with 24 bits of 
color very well, and this sort of color depth offers more color 
resolution than many applications call for. To this end, the JPEG 
library to be discussed in this chapter can be told to automatically 
dither JPEG files being read down to 256 colors. When this feature is 
enabled, a JPEG file will look like a 256-color image to an application 
reading it. 

It’s important to know what’s really going in when you tell a JPEG 
reader to do this. To begin with, the JPEG dithering function has been 
designed to be fast rather than pretty. It uses the fixed 256-color 
orthogonal palette discussed in chapter 2 for all images, rather than 
quantizing an optimal palette for each image being read. This means 
that all 256-color images read from JPEG files will have the same 
palette, which is handy for applications that might be called upon to 
display multiple images at once, such as web browsers. However, it 
also means that the dithering can get pretty crunchy. 

In addition, if you promote a 256-color image to 24 bits and store it in 
a JPEG file, it will already have been dithered once to get it into a 
256-color format to begin with. If it’s read out of the JPEG file as a 
256-color image, it will be dithered a second time. This can degrade 
an image a lot more than JPEG compression itself will. 

The potential that JPEG offers for seriously mangling images is 
considerable, although you can avoid much of it by understanding 
what JPEG really does and using it accordingly. Among the most 
important considerations in using JPEG files is not allowing your 
images to be successively read from and then written back to JPEG 
files and not letting previously dithering images be written to JPEG 
files and then dithered a second time. 

The potential for storing images in otherwise impossibly small files has 
made JPEG exceedingly popular in telecommunications circles. As I 






write this, JPEG is one of the two formats actively in use for images 
on the World Wide Web. The other, of course, is GIF. The two formats 
are not interchangeable, each offering features the other does not. 
Specifically, JPEG embodies the following considerations: 

>- It can compress photorealistic images smaller than GIF, albeit 
with some loss of detail. 

>- The basic JFIF JPEG format does not include a facility for 
interlacing images—an extended JPEG standard, called 
“progressive” JPEG, has been proposed as I write this, which 
does. 

>- JPEG files do not support transparency. 

For practical purposes, JPEG can’t be used to store line art. 

>- JPEG files can’t handle animation. 

The JPEG compression algorithm is a bit inscrutable, although, 
because a third party JPEG library will be doing all the work, you’re 
safe in permitting it to remain that way. The JFIF format is somewhat 
chunk-oriented and similar in concept to the structure of a GIF or 
PNG file, and it’s possible to store information like comments and 
copyright text along with the image in a GIF file. 

A JPEG file always begins with a byte containing Oxff. Having said 
this, note that JPEG files from a Macintosh system might have a 
Macbinary header before the first byte of the file proper—check out 
chapter 3 for a complete discussion of Macbinary headers. Following 
this there should be an SOI marker, for “start of image.” This byte 
will contain 0xd8. 

The rest of the JPEG file being read will consist of a series of markers 
followed by some data. Sadly, these aren’t as easy to unpack as the 
blocks in a GIF file or the chunks supported by PNG, as a JPEG 
reader must recognize the markers it encounters and know how to 
deal with them. For example, a COM marker, Oxfe, defines a 
comment. The first two bytes represent a long integer that defines the 
length of the subsequent text. Multiple-byte objects in JPEG files are 
stored in the correct order for a PC’s processor. 








You might want to dig through the IJG JPEG library source code on 
the companion CD-ROM for this book if you’d like to work out the 
details of parsing a JPEG file. There are few applications in which 
doing so is necessary, however. 

The JPGLIB library 

The JPEG library in this book is based in the Independent JPEG 
Group’s source code. As with the other third-party libraries used in 
this book, this one was not designed specifically to get along with 
either Windows or OS/2. It’s agreeably modular, however, and the 
version on the companion CD-ROM for this book has been fine-tuned 
to run in these environments. As with the earlier libraries, the only 
aspect of the IJG JPEG libraries that needs customization for Windows 
and Warp is its memory management. 

The source code for JPGLIB.CPP can be found in Fig. 9-2. 

The IJG JPEG library embodies a laudable degree of transparency— 
you can use it to read and write JPEG files without knowing anything 
about what it does behind your back. The ReadGraphicFile function 
in JPGLIB illustrates how to make the appropriate calls into the library 
to read a JPEG file. 

The IJG library uses C language streamed file functions, necessitating 
that the source file being read be opened with fopen. It also wants to 
use longjmp to abort prematurely if it gets into trouble while it’s 
reading a file, or something else that will allow it to jump out of 
wherever it is when something goes wrong. 

In fact, what really happens when an error occurs during a JPEG read 
is that the library will call a user-defined exit routine to bail out. It’s 
defined here as my_error_exit. Under a DOS application this might 
just return to DOS. In this case it’s what will call longjmp. This being 
the case, make sure you call setjmp before you start unpacking an 
image. 






/* Figure 9-2 

JPG Library 

Copyright (c) 1995 Alchemy Mindworks Inc. 

*/ j 

#include <windows.h> 

#include <stdio.h> 

#include <string.h> 

#include <stdlib.h> 

#include <setjmp.h> 
ttinclude "winbit.h" 

#include "jpeglib.h" 

// Set this TRUE for 256-colour JPEG images 
//or FALSE it for 24-bit JPEG images 

#define COLOURMAPPED TRUE ! 

ttdefine JPEG_QUALITY 75 // This is the write quality factor 

HANDLE hlnst; 

WORD error=NO_ERROR; 

#ifdef WIN32 

ttpragma argsused 

DLL_EXPORT (BOOL) DllEntryPoint(HINSTANCE hlnstance, 

DWORD wDataSeg,LPVOID lpCmdLine) 

{ 

hlnst=hlnstance; 


return(TRUE); 

} 

#else 

#pragma argsused 

DLL_EXPORT (int) LibMain(HANDLE hlnstance, 

WORD wDataSeg,WORD wHeapSize, LPSTR lpCmdLine) 

{ 

hlnst=hlnstance; 

if (wHeapSize > 0) UnlockData(O); 
return(TRUE); 

} 

#pragma argsused 

DLL_EXPORT (int) WEP(int nParameter) 

{ 

return (TRUE); 

} 

#endif 



The JPGLIB.CPP source code. 
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DLL_EXPORT (LPSTR) GetFileExtension() 

{ 

return("JPG"); 

} 

DLL_EXPORT (WORD) GetLibraryVersion() 

{ 

return ( (VERSION « 8) ! SUBVERSION); 

} 

struct my_error_mgr { 

struct jpeg_error_mgr pub; 
jmp_buf setjmp_buffer; 

}; 


typedef struct my_error_mgr * my_error_ptr; 

METHODDEF void my_error_exit (j_conimon_ptr cinfo) 

{ 

m y_error_ptr myerr=(my_error_ptr)cinfo->err; 

(*cinfo->err->output_message)(cinfo); 
longjmp(myerr->setjmp_buffer, 1); 

} 

#define DestroyAllObjects(err,success) {\ 

if(fp != NULL) fclose(fp);\ 

if(!success && handle != NULL) GlobalFree(handle);\ 
error=err;\ 

} 

DLL_EXPORT (HANDLE) GetFilelnformation(LPSTR path) 

{ 

struct jpeg_decompress_struct cinfo; 
struct my_error_mgr jerr; 

FILE *fp=NULL; 

HANDLE handle=NULL; 
char palette[768]; 
int bits; 

Initialize(); 

if((fp=fopen(path,"rb"))==NULL) { 

DestroyAllObjects(BAD_OPEN,FALSE); 
return(NULL); 

} 

cinfo.err = jpeg_std_error(&jerr.pub); 
j err.pub.error_exit = my_error_exit; 

if(setjmp(jerr.setjmp_buffer)) { 

DestroyAllObjects(BAD_ALLOC,FALSE); 
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return(NULL); 

} 

jpeg_create_decompress(&cinfo); 

jpeg_stdio_src(&cinfo,fp); 

jpeg_read_header(&cinfo,TRUE); 

bits=cinfo.num_components<<3; 

if(bits==24) GetOrthoPalette(palette); 
else GetGreyPalette(palette); 

#if COLOURMAPPED 

if(bits==24) bits=8; 

#endif 

if((handle=CreateDibHeader(cinfo.image_width, 
cinfo.image_height,palette,bits))==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

} 

jpeg_destroy_decompress(&cinfo); 

DestroyAllObjects(NO_ERROR,TRUE); 
return(handle); 


} 

#undef DestroyAllObj ects() 

#define DestroyAllObjects(err , success) {\ 

if(fp != NULL) fclose(fp);\ 
if(lpbi != NULL) GlobalUnlock(handle);\ 
if(!success && handle != NULL) GlobalFree(handle);\ 
error=err;\ 

} 

DLL_EXPORT (HANDLE) ReadGraphicFile(LPSTR path) 

{ 

struct jpeg_decompress_struct cinfo; 

struct my_error_mgr jerr; 

FILE * fp=NULL; 

JSAMPARRAY buffer; 

LPRGBQUAD lprgb; 

LPBITMAPINFOHEADER lpbi=NULL; 

HANDLE handle=NULL; 

HPSTR pd; 

char palette[768]; 

int i,bits,row_stride; 


Figure 9-2 







Figure 9-2 Continued. 

Initialize() ; 

if ( (fp=fopen(path,"rb"))==NULL) { 

DestroyAllObj ects(BAD_OPEN,FALSE); 
return(NULL); 

} 

cinfo.err=jpeg_std_error(&jerr.pub); 
jerr.pub.error_exit = my_error_exit; 

if(setjmp(jerr.setjmp_buffer)) { 

DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

i } 

jpeg_create_decompress(&cinfo); 

jpeg_stdio_src(&cinfo,fp); 

jpeg_read_header(&cinfo,TRUE); 

bits=cinfo.num_components<<3; 

if(bits==24) GetOrthoPalette(palette); 
else GetGreyPalette(palette); 

#if COLOURMAPPED 

if(bits==24) { 
bits=8; 

cinfo.quantize_colors=TRUE; 

i > 

#endif 

jpeg_start_decompress(&cinfo); 

if((handle=CreateDib(cinfo.image_width, 

cinfo.image_height,palette,bits))==NULL) { 

DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

} 

if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(handle)) ==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(NULL); 

} 



row_stride=cinfo.output_width*cinfo.output_components; 

buffer=(*cinfo.mem->alloc_sarray) 

( (j_common__ptr) &cinfo, JPOOL_IMAGE, row_stride, 1) ; 

pd=LPBimage(lpbi)+(DWORD)LPBlinewidth(lpbi)* 
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(DWORD)LPBdepth(lpbi); 

while(cinfo.output_scanline < cinfo.output_height) { 

pd-=(DWORD)LPBlinewidth(lpbi); 
jpeg_read_scanlines (Secinfo, buffer, 1) ; 

hmemcpy(pd,buffer[0],LPBlinewidth(lpbi)); 


if(cinfo.colormap != NULL) { 

lprgb=LPBcolourmap(lpbi); 

for(i=0;i<LPBcolours(lpbi) && i < 256;++i) { 

lprgb->rgbRed=cinfo.colormap[2] [i] ; 
lprgb->rgbGreen=cinfo.colormap[1][i]; 
lprgb->rgbBlue=cinfo.colormap[0][i]; 
++lprgb; 

} 

} 

jpeg_finish_decompress(&cinfo); 
jpeg_destroy_decompress(&cinfo); 

DestroyAllObj ects(NO_ERROR,TRUE); 
return(handle); 


} 

#undef DestroyAllObjects() 

#define DestroyAllObjects(err,success) {\ 

if(fp != NULL) fclose(fp);\ 

if(fp ! = NULL StSc ! success) DeleteFile (path) ; \ 

if(linebuffer != NULL) FixedGlobalFree(linebuffer);\ 

if(lpbi != NULL) GlobalUnlock(handle);\ 

error=err;\ 

} 

DLL_EXPORT (WORD) WriteGraphicFile(LPSTR path, HANDLE handle) 

{ 

struct jpeg_error_mgr jerr; 
struct jpeg_compress_struct cinfo; 

JSAMPROW row_pointer[1]; 

FILE * fp=NULL; 

LPBITMAPINFOHEADER lpbi=NULL; 

LPSTR linebuffer=NULL,extrabuffer=NULL,ps; 

HPSTR pd; 

char palette[768] ; 
int c,i; 

if((lpbi=(LPBITMAPINFOHEADER)GlobalLock(handle))==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(FALSE); 

} 


Figure 9-2 
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if((linebuffer= 

FixedGlobalAlloc(LPBlinewidth(lpbi)+1024)) == NULL) { 
DestroyAllObj ects(BAD_ALLOC,FALSE) ; 
return(FALSE); 

} 

if((extrabuffer= 

FixedGlobalAlloc(LPBwidth(lpbi)*RGB_SIZE+1024)) ==NULL) { 
DestroyAllObjects(BAD_ALLOC,FALSE); 
return(FALSE); 

} 

if(LPBbits(lpbi) <= 8) 

GetDibPalette((LPBITMAPINFO)lpbi,palette); 

cinfo.err = jpeg_std_error(&jerr); 

Dpeg_create_compress(&cinfo); 

if((fp=fopen(path,"wb"))==NULL) { 

DestroyAllObjects(BAD_ALLOC,FALSE); 
return(FALSE); 

} 

jpeg_stdio_dest(&cinfo,fp); 

cinfo.image_width=LPBwidth(lpbi); 
cinfo.image_height=LPBdepth(lpbi); 
cinfo.input_components=3; 
cinfo.in_color_space=JCS_RGB; 

jpeg_set_defaults(&cinfo); 

jpeg_set_quality(&cinfo,JPEG_QUALITY,TRUE); 

jpeg_start_compress(&cinfo,TRUE); 

pd=LPBimage(lpbi)+(DWORD)LPBlinewidth(lpbi)* 

(DWORD)LPBdepth(lpbi); 

while(cinfo.next_scanline < cinfo.image_height) { 
pd-=(DWORD)LPBlinewidth(lpbi); 
hmemcpy(linebuffer,pd,LPBlinewidth(lpbi)); 
switch(LPBbits(lpbi)) { 
case 1: 

for(i=0;icLPBwidth(lpbi);++i) { 

if(linebuffer[i » 3] & 
masktable[i & 0x0007]) { 

extrabuffer[i*RGB_SIZE+RGB_RED]=255; 
ext rabu f f er[i* RGB_SIZE+RGB_GREEN]=255; 
extrabuffer[i*RGB_SIZE+RGB_BLUE]=255; 

} 

else { 

extrabuffer[i*RGB_SIZE+RGB_RED]=0; 
extrabuffer[i*RGB_SIZE+RGB_GREEN]=0; 
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extrabuffer[i*RGB_SIZE+RGB_BLUE]=0; 

} 

} 

break; 
case 4: 

for(i=0;i<LPBwidth(lpbi);++i) { 

c=GetChunkyPixel(linebuffer,i); 
ps=palette+c*RGB_SIZE; 

extrabuffer[i*RGB_SIZE+RGB_BLUE]=*ps++; 
extrabuffer[i*RGB_SIZE+RGB_GREEN]=*ps++; 
extrabuffer[i*RGB_SIZE+RGB_RED]=*ps++; 

} 

break; 

case 8: 

for(i=0;i<LPBwidth(lpbi);++i) { 

ps=palette+linebuffer[i]*RGB_SIZE; 
extrabuffer[i*RGB_SIZE+RGB_BLUE]=*ps++; 
extrabuffer[i* RGB_SIZE+RGB_GREEN]=*ps++; 
extrabuffer[i*RGB_SIZE+RGB_RED]=*ps++; 

} 

break; 
case 24: 

lmemcpy(extrabuffer, 

linebuffer,LPBlinewidth(lpbi)); 
break; 

} 

row_pointer[0] = extrabuffer; 
jpeg_write_scanlines(&cinfo,row_pointer,1); 

} 

jpeg_finish_compress(&cinfo); 
jpeg_destroy_compress(&cinfo); 

DestroyAllObjects(NO_ERROR,TRUE); 

return(TRUE); 

} 

#undef GetLine() 

DLL_EXPORT (WORD) GetError(LPSTR text) 

{ 

if(text != NULL) lstrcpy(text,GetErrorText(error)); 
return(error); 

} 

DLL_EXPORT (LPSTR) GetCopyright() 

{ 

return("Copyright \251 1995 Alchemy Mindworks Inc."); 

} 

DLL_EXPORT (LPSTR) GetNotice() 

{ 
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return("JPEG supports from one to 24 bits of colour.\n\n" 
"This software is based in part on the work of\n" 

"the Independent JPEG Group." 

) ; 


The information required to unpack a JPEG file is maintained in a 
jpeg_decompress_struct, which the jpeg_create_decompress 
function initializes. The jpeg_read_header function steps through the 
initial markers in the source file and writes information about them to 
the jpeg_decompress_struct. A call to jpeg_start_decompress will 
get the file ready to be unpacked. The jpeg__read_scanlines function 
can be used to read the image lines one at a time into a buffer. Note 
that the scan lines come out of a JPEG file first to last—this order 
must be reversed for a device-independent bitmap. The 24-bit pixels 
unpacked by jpeg_read_Scanlines have their color components 
ordered the same way as Windows and Warp expect them. 

The process of reading a JPEG file is slightly more involved if it’s 
required as a 256-color bitmap. In JPGLIB, this is defined by setting 
the COLOURMAPPED define at the top of the source file. In a real- 
world application of JPEG, you’d probably want to make this option 
user-definable, or perhaps dependent on the screen driver color depth 
of the machine running your software. To have the IJG JPEG library 
read a JPEG file as a 256-color image, the quantize_colors field of 
the jpeg_decompress_struct for the file must be set true. In this 
case, the image palette will be the same orthogonal palette that’s 
generated by the GetOrthoPalette function in WINBIT.CPP. 

Writing a JPEG file is a bit more complex than reading one because 
the WriteGraphicFile function in JPGLIB has to be able to cope with 
the possibility of someone asking it to write an image with fewer than 
24 bits of color. Specifically, it must be able to promote these palette- 
driven bitmaps to true color. 


It should be pretty easy to see what WriteGraphicFile is up to. It 
begins by creating the destination JPEG file and initializing a 
jpeg_compress_struct object with the image dimensions and color 







depth. Keep in mind that, while they’re not supported in 
WriteGraphicFile, 8-bit gray scale JPEG files do exist. The quality 
factor is set by calling jpeg_set_quality. Once again, this value is hard 
wired into JPGLIB as the define JPEG_QUALITY —you will probably 
want to make this user-definable for a real-world application that 
writes JPEG files. 

The while loop in WriteGraphicFile compresses the source image 
lines by calling jpeg_write_scanlines once for each line. This loop 
also illustrates how image lines are promoted to true color. 

Using JPEG files 

Immensely popular because of its compression qualities, JPEG is 
widely supported mostly by applications that deal with image files as I 
write this. It’s essential if you plan to do anything with World Wide 
Web page creation. 

As of this writing, the Independent JPEG Group freely offers its JPEG 
libraries to be used in other applications, with the sole condition being 
that it be acknowledged. A suitable acknowledgment can be found in 
the GetNotice function of JPGLIB. 
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